zkgridster

ZK wrapper for gridster.js, a jQuery plugin that makes building intuitive draggable layouts from elements spanning multiple columns.

Download

Maven

<dependency>
	<groupId>org.zkoss</groupId>
	<artifactId>zkgridster</artifactId>
	<version>0.1.5</version>
</dependency>

Gradle

runtime group: 'org.zkoss', name: 'zkgridster', version: '0.1.4'

Demo

A small demo app is included to showcase functionality and use. To run the demo with Maven, start Jetty:

mvn jetty:run

and navigate to http://localhost:8080/zkgridster/

Quick Start

All features are supported in both ZUL and Java. The two following code snippets are functionally equivalent. Both will create a Gridster component with two Griditems, one taller (sizeX="2") and one wider (sizeY="2"). Note that a Griditem can contain any ZK component.

ZUL

<gridster>
    <griditem row="1" col="1" sizeX="2" sizeY="1">
    	<label value="Hello"/>
    </griditem>
    <griditem row="1" col="3" sizeX="1" sizeY="2">
    	<label value="World!"/>
    </griditem>
<gridster>

Java

Gridster gridster = new Gridster();
Griditem item1 = new Griditem();
item1.setRow(1);
item1.setCol(1);
item1.setSizeX(2);
item1.setSizeY(1);
item1.appendChild(new Label("Hello"));
item1.setParent(gridster);
Griditem item2 = new Griditem();
item2.setRow(1);
item2.setCol(3);
item2.setSizeX(1);
item2.setSizeY(2);
item2.appendChild(new Label("World!"));
item2.setParent(gridster);

Advanced Examples

Refer to the gridster.js documentation for a list of all features and examples of their usage. zkgridster wraps all original features and function names in Java are analogous to those in JavaScript.

Gridster Parameters

The Gridster component accepts a number of

<gridster baseWidth="100"
          baseHeight="100"
          widgetMarginVertical="10"
          widgetMarginHorizontal="10"
          resizeEnabled="true"
          resizeMaxCols="5"
          resizeMaxRows="3"
          resizeMinCols="2"
          resizeMinRows="2"
          style="background-color: gainsboro">
    <griditem row="1" col="1" sizeX="1" sizeY="1"/>
    <griditem row="2" col="1" sizeX="1" sizeY="1"/>
    <griditem row="3" col="1" sizeX="1" sizeY="1"/>
    
    <griditem row="1" col="2" sizeX="2" sizeY="1"/>
    <griditem row="2" col="2" sizeX="2" sizeY="2"/>
    
    <griditem row="1" col="4" sizeX="1" sizeY="1"/>
    <griditem row="2" col="4" sizeX="2" sizeY="1"/>
    <griditem row="3" col="4" sizeX="1" sizeY="1"/>
    
    <griditem row="1" col="5" sizeX="1" sizeY="1"/>
    <griditem row="3" col="5" sizeX="1" sizeY="1"/>
    
    <griditem row="1" col="6" sizeX="1" sizeY="1"/>
    <griditem row="2" col="6" sizeX="1" sizeY="2"/>
<gridster>

zkgridster Parameter	gridster.js Analogue
widgetMarginHorizontal	widget_margins
widgetMarginVertical	widget_margins
widgetBaseWidth	widget_base_dimensions
widgetBaseHeight	widget_base_dimensions
extraRows	extra_rows
extraCols	extra_cols
minRows	min_rows
minCols	min_cols
maxCols	max_cols
maxSizeX	max_size_x
maxSizeY	max_size_y
resizeEnabled	resize.enabled
resizeAxes	resize.axes
resizeMaxRows	resize.max_size
resizeMaxCols	resize.max_size
resizeMinRows	resize.min_size
resizeMinCols	resize.min_size

Event Listening

zkgridster provides native ZK server side events for client side interactions. Supported events are:

Event Name	Java Static Variable	gridster.js Analogue	Event Data	Description
onChange	GridsterEvents.ON_CHANGE	none	Serialized State	Fired when the Gridster is first rendered with it's data, and when the state changes, either by moving or resizing a Griditem.
onDragStart	GridsterEvents.ON_DRAG_START	draggable.start	none	Fired once when the user starts dragging a Griditem
onDrag	GridsterEvents.ON_DRAG	draggable.drag	none	Fired as the user moves their mouse while dragging a Griditem
onDragStop	GridsterEvents.ON_DRAG_STOP	draggable.stop	none	Fired once when the user stops dragging a Griditem
onResizeStart	GridsterEvents.ON_RESIZE_START	resize.start	none	Fired once when the user starts resizing a Griditem
onResize	GridsterEvents.ON_RESIZE	resize.resize	none	Fired as the user moves their mouse while resizing a Griditem
onResizeStop	GridsterEvents.ON_RESIZE_STOP	resize.stop	none	Fired once when the user stops resizing a Griditem

Note: All events are fired on the Gridster component, no events are fired for individual Griditems. This is because, for example, resizing a single item can cause a reorganization of all other items; it is difficult to track individual changes.�

Event Listening - Example

gridster.addEventListener(GridsterEvents.ON_DRAG, new EventListener<Event>() {
	@Override
	public void onEvent(Event event) {
		// Handle dragging
	}
});

Event Listening - State

Note that no data is passed for any event other than onChange, where the data is a org.zkoss.json.JSONObject of the serialized state. Normal use, however, should not require you interact with this serialized state directly. Instead, this is used internally to keep the server state in-sync with the client at all times. As such, you can assume the server state is accurate when handling events server side. For example:

gridster.addEventListener(GridsterEvents.ON_CHANGE, new EventListener<Event>() {
	@Override
	public void onEvent(Event event) {
		Gridster gridster = (Gridster) event.getTarget();
		for(GridItem item : gridster.getGridItems()) {
  		    // item values already reflect recent client side changes:
		    System.out.println(item.getUuid() + ": " +
		    		" row=" + item.getRow()
		    		" col=" + item.getCol()
		    		" sizeX=" + item.getSizeX()
		    		" sizeY=" + item.getSizeY()
		    );
		}
	}
});

Requirements

zkgridster requires a minimum of Java 7 and ZK 7.0.3

License

Both zkgridster and gridster.js are distributed under the MIT license.

Credit

gridster.js is build by Ducksboard with the help of all these wonderful people.

zkgridster is written by Sean Connolly.