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>

Event Listening

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

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.