Examples of org.zkoss.zul.Grid

A grid is an element that contains both rows and columns elements. It is used to create a grid of elements. Both the rows and columns are displayed at once although only one will typically contain content, while the other may provide size information.

Events: onAfterRender
onAfterRender is sent when the model's data has been rendered.(since 5.0.4)

Besides creating {@link Row} programmingly, you can assigna data model (a {@link ListModel} or {@link GroupsModel} instance) to a grid via{@link #setModel(ListModel)} or {@link #setModel(GroupsModel)}and then the grid will retrieve data by calling {@link ListModel#getElementAt} when necessary.

Besides assign a list model, you could assign a renderer (a {@link RowRenderer} instance) to a grid, such thatthe grid will use this renderer to render the data returned by {@link ListModel#getElementAt}. If not assigned, the default renderer, which assumes a label per row, is used. In other words, the default renderer adds a label to a row by calling toString against the object returned by {@link ListModel#getElementAt}

There are two ways to handle long content: scrolling and paging. If {@link #getMold} is "default", scrolling is used if {@link #setHeight}is called and too much content to display. If {@link #getMold} is "paging", paging is used if two or more pages arerequired. To control the number of rows to display in a page, use {@link #setPageSize}.

If paging is used, the page controller is either created automatically or assigned explicity by {@link #setPaginal}. The paging controller specified explicitly by {@link #setPaginal} is calledthe external page controller. It is useful if you want to put the paging controller at different location (other than as a child component), or you want to use the same controller to control multiple grids.

Default {@link #getZclass}: z-grid.(since 3.5.0)

To have a grid without stripping, you can specify a non-existent style class to {@link #setOddRowSclass}.

Clustering and Serialization

When used in a clustering environment, you have to make {@link RowRenderer}( {@link #setRowRenderer}) and {@link ListModel} ({@link #setModel}) either serializable or re-assign them when {@link #sessionDidActivate} is called.

Render on Demand (rod)

[ZK EE] [Since 5.0.0]

For huge data, you can turn on Grid's ROD to request ZK engine to load from {@link ListModel} only the required data chunk and create only the required{@link Row}s in memory and render only the required DOM elements in browser. So it saves both the memory and the processing time in both server and browser for huge data. If you don't use the {@link ListModel} with the Grid, turn on the ROD will still have ZK engine to render only a chunk of DOM elements in browser so it at least saves the memory and processing time in browser. Note that ROD works only if the Grid is configured to has a limited "view port" height. That is, either the Grid is in the "paging" mold or you have to {@link #setHeight(String)} or {@link #setVflex(String)} of the Grid to make ROD works.

You can turn on/off ROD for all Grids in the application or only for a specific Grid. To turn on ROD for all Grids in the application, you have to specify the Library Property "org.zkoss.zul.grid.rod" to "true" in WEB-INF/zk.xml. If you did not specify the Library Property, default is false.

  org.zkoss.zul.grid.rod true

To turn on ROD for a specific Grid, you have to specify the Grid's attribute map with key "org.zkoss.zul.grid.rod" to true. That is, for example, if in a zul file, you shall specify <custom-attributes> of the Grid like this:

You can mix the Library Property and <custom-attributes> ways together. The <custom-attributes> way always takes higher priority. So you can turn OFF ROD in general and turn ON only some specific Grid component. Or you can turn ON ROD in general and turn OFF only some specific Grid component.

Since only partial {@link Row}s are created and rendered in the Grid if you turn the ROD on, there will be some limitations on accessing {@link Row}s. For example, if you call

 Row rowAt100 = (Row) getRows().getChildren().get(100);

The {@link Row} in index 100 is not necessary created yet if it is not in thecurrent "view port" and you will get "null" instead.

And it is generally a bad idea to "cache" the created {@link Row} in yourapplication if you turn the ROD on because rows might be removed later. Basically, you shall operate on the item of the ListModel rather than on the {@link Row} if you use the ListModel and ROD.

@author tomyeh @see ListModel @see RowRenderer @see RowRendererExt