Package org.zkoss.zul

Class Grid

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, Component, Scope, ComponentCtrl, Paginated
    public class Grid
extends MeshElement
    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 Row programmatically, you can assign a data model (a ListModel or GroupsModel instance) to a grid via setModel(ListModel) or setModel(GroupsModel) and then the grid will retrieve data by calling ListModel.getElementAt(int) when necessary.

    Besides assign a list model, you could assign a renderer (a RowRenderer instance) to a grid, such that the grid will use this renderer to render the data returned by ListModel.getElementAt(int). 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 ListModel.getElementAt(int)

    There are two ways to handle long content: scrolling and paging. If AbstractComponent.getMold() is "default", scrolling is used if setHeight(java.lang.String) is called and too much content to display. If AbstractComponent.getMold() is "paging", paging is used if two or more pages are required. To control the number of rows to display in a page, use setPageSize(int).

    If paging is used, the page controller is either created automatically or assigned explicitly by setPaginal(org.zkoss.zul.ext.Paginal). The paging controller specified explicitly by setPaginal(org.zkoss.zul.ext.Paginal) is called the 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 getZclass(): z-grid.(since 3.5.0)

    To have a grid without stripping, you can specify a non-existent style class to setOddRowSclass(java.lang.String).

    Clustering and Serialization

    When used in a clustering environment, you have to make RowRenderer (setRowRenderer(org.zkoss.zul.RowRenderer<?>)) and ListModel (setModel(org.zkoss.zul.ListModel<?>)) either serializable or re-assign them when sessionDidActivate(org.zkoss.zk.ui.Page) 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 ListModel only the required data chunk and create only the required Rows 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 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 setHeight(String) or 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.

    
	<library-property>
		<name>org.zkoss.zul.grid.rod</name>
		<value>true</value>
	</library-property>

    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:

    
	<grid ...>
    <custom-attributes org.zkoss.zul.grid.rod="true"/>
  </grid>

    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 Rows are created and rendered in the Grid if you turn the ROD on, there will be some limitations on accessing Rows. For example, if you call 

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

    The Row in index 100 is not necessary created yet if it is not in the current "view port" and you will get "null" instead.

    And it is generally a bad idea to "cache" the created Row in your application 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 Row if you use the ListModel and ROD.

    Custom Attributes

    org.zkoss.zul.grid.rod
    Specifies whether to enable ROD (render-on-demand).
    Notice that you could specify this attribute in any of its ancestor's attributes. It will be inherited.
    org.zkoss.zul.grid.autoSort
    .(since 5.0.7)
    Specifies whether to sort the model when the following cases:
    1. setModel(org.zkoss.zul.ListModel<?>) is called and Column.setSortDirection(java.lang.String) is set.
    2. Column.setSortDirection(java.lang.String) is called.
    3. Model receives ListDataEvent and Column.setSortDirection(java.lang.String) is set.
    If you want to ignore sort when receiving ListDataEvent, you can specifies the value as "ignore.change".
    Notice that you could specify this attribute in any of its ancestor's attributes. It will be inherited.
    org.zkoss.zul.grid.preloadSize
    .(since 5.0.8)
    Specifies the number of rows to preload when receiving the rendering request from the client.

    It is used only if live data (setModel(ListModel) and not paging (getPagingChild()).

    org.zkoss.zul.grid.initRodSize
    .(since 5.0.8)
    Specifies the number of rows rendered when the Grid first render.

    It is used only if live data (setModel(ListModel) and not paging (getPagingChild()).

    Author:
    tomyeh
    See Also:
    ListModel, RowRenderer, RowRendererExt, Serialized Form