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 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.
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
There are two ways to handle long content: scrolling and paging.
If
#getMold is "default", scrolling is used if
#setHeightis called and too much content to display.
If
#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.
If paging is used, the page controller is either created automatically
or assigned explicitly by
#setPaginal.
The paging controller specified explicitly by
#setPaginal 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.
Clustering and Serialization
When used in a clustering environment, you have to make
RowRenderer(
#setRowRenderer) and
ListModel (
#setModel) either
serializable or re-assign them when
#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
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.
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
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:
-
#setModel is called and
Column#setSortDirection is set.
-
Column#setSortDirection is called.
- Model receives
ListDataEvent and
Column#setSortDirection 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).