public class Grid extends MeshElement
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)
.
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.
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
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 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 Row
s are created and rendered in the Grid if
you turn the ROD on, there will be some limitations on accessing Row
s.
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.
setModel(org.zkoss.zul.ListModel<?>)
is called and Column.setSortDirection(java.lang.String)
is set.Column.setSortDirection(java.lang.String)
is called.ListDataEvent
and Column.setSortDirection(java.lang.String)
is set.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.It is used only if live data (setModel(ListModel)
and
not paging (getPagingChild()
).
It is used only if live data (setModel(ListModel)
and not paging
(getPagingChild()
).
ListModel
,
RowRenderer
,
RowRendererExt
,
Serialized FormModifier and Type | Class and Description |
---|---|
protected class |
Grid.ExtraCtrl
A utility class to implement
HtmlBasedComponent.getExtraCtrl() . |
MeshElement.InternalPaging
CSS_FLEX_AUTO_DISABLED_COUNT
Constructor and Description |
---|
Grid() |
Modifier and Type | Method and Description |
---|---|
void |
beforeChildAdded(org.zkoss.zk.ui.Component newChild,
org.zkoss.zk.ui.Component refChild) |
Object |
clone() |
String |
getAlign()
Deprecated.
As of release 5.0, use CSS instead.
|
org.zkoss.zk.ui.Component |
getCell(int row,
int col)
Returns the specified cell, or null if not available.
|
Columns |
getColumns()
Returns the columns.
|
String |
getEmptyMessage()
Returns the message to display when there are no items
|
Object |
getExtraCtrl() |
Foot |
getFoot()
Returns the foot.
|
Frozen |
getFrozen()
Returns the frozen child.
|
<D,G,F> GroupsModel<D,G,F> |
getGroupsModel()
Returns the groups model associated with this grid, or null
if this grid is associated with a
ListModel
or not associated with any list data model. |
Collection<org.zkoss.zk.ui.Component> |
getHeads()
Returns a collection of heads, including
getColumns()
and auxiliary heads (Auxhead ) (never null). |
String |
getInnerWidth()
Returns the inner width of this component.
|
<T> ListModel<T> |
getListModel()
Returns the list model associated with this grid, or null
if this grid is associated with a
GroupsModel
or not associated with any list data model. |
<T> ListModel<T> |
getModel()
Returns the model associated with this grid, or null
if this grid is not associated with any list data model.
|
String |
getOddRowSclass()
Returns the style class for the odd rows.
|
Paginal |
getPaginal()
Returns the paging controller, or null if not available.
|
Paging |
getPagingChild()
Returns the child paging controller that is created automatically,
or null if mold is not "paging", or the controller is specified externally
by
setPaginal(org.zkoss.zul.ext.Paginal) . |
int |
getPreloadSize()
Deprecated.
As of release 5.0.8, use custom attributes (org.zkoss.zul.listbox.preloadSize) instead.
Returns the number of rows to preload when receiving
the rendering request from the client.
Default: 50. (since 6.0.1) It is used only if live data ( Note: if the "pre-load-size" attribute of component is specified, it's prior to the original value.(@since 3.0.4) |
<T> RowRenderer<T> |
getRowRenderer()
Returns the renderer to render each row, or null if the default
renderer is used.
|
Rows |
getRows()
Returns the rows.
|
int |
getVisibleRows()
Returns the visible rows.
|
String |
getZclass() |
boolean |
insertBefore(org.zkoss.zk.ui.Component newChild,
org.zkoss.zk.ui.Component refChild) |
protected boolean |
isAutohidePaging() |
boolean |
isFixedLayout()
Deprecated.
since 5.0.0, use !
MeshElement.isSizedByContent() instead |
boolean |
isVflex()
Returns whether to grow and shrink vertical to fit their given space,
so called vertical flexibility.
|
void |
onAfterRender() |
void |
onInitRender()
Handles a private event, onInitRender.
|
void |
onPageAttached(org.zkoss.zk.ui.Page newpage,
org.zkoss.zk.ui.Page oldpage) |
void |
onPageDetached(org.zkoss.zk.ui.Page page) |
void |
onPagingInitRender()
Handles a private event, onPagingInitRender.
|
protected Paginal |
pgi()
Returns the instance of the @{link Paginal}
|
boolean |
removeChild(org.zkoss.zk.ui.Component child) |
void |
renderAll()
Renders all
Row if not loaded yet,
with getRowRenderer() . |
void |
renderItems(Set<? extends Row> rows) |
protected void |
renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) |
void |
renderRow(Row row)
Renders the specified
Row if not loaded yet,
with getRowRenderer() . |
void |
renderRows(Set<? extends Row> rows)
Renders a set of specified rows.
|
void |
scrollToIndex(int index)
Scroll to the specified row by the given index.
|
void |
service(org.zkoss.zk.au.AuRequest request,
boolean everError)
Processes an AU request.
|
void |
sessionDidActivate(org.zkoss.zk.ui.Page page) |
void |
sessionWillPassivate(org.zkoss.zk.ui.Page page) |
void |
setActivePage(int pg)
Sets the active page (starting from 0).
|
void |
setAlign(String align)
Deprecated.
As of release 5.0, use CSS instead.
|
void |
setEmptyMessage(String emptyMessage)
Sets the message to display when there are no items
|
void |
setFixedLayout(boolean fixedLayout)
Deprecated.
since 5.0.0, use
MeshElement.setSizedByContent(boolean) (!fixedLayout) instead |
void |
setHeight(String height) |
void |
setInnerWidth(String innerWidth)
Sets the inner width of this component.
|
void |
setModel(GroupsModel<?,?,?> model)
Sets the groups model associated with this grid.
|
void |
setModel(ListModel<?> model)
Sets the list model associated with this grid.
|
void |
setMold(String mold)
Sets the mold to render this component.
|
void |
setOddRowSclass(String scls)
Sets the style class for the odd rows.
|
void |
setPageSize(int pgsz)
Sets the page size, a.k.a., the number rows per page.
|
void |
setPaginal(Paginal pgi)
Specifies the paging controller.
|
void |
setPreloadSize(int sz)
Deprecated.
As of release 5.0.8, use custom attributes (org.zkoss.zul.listbox.preloadSize) instead.
Sets the number of rows to preload when receiving
the rendering request from the client.
It is used only if live data ( |
void |
setRowRenderer(RowRenderer<?> renderer)
Sets the renderer which is used to render each row
if
getModel() is not null. |
void |
setRowRenderer(String clsnm)
Sets the renderer by use of a class name.
|
void |
setVflex(boolean vflex)
Sets whether to grow and shrink vertical to fit their given space,
so called vertical flexibility.
|
void |
setVflex(String flex) |
void |
setVisibleRows(int visibleRows)
Sets the visible rows.
|
checkBeforeSetRows, evalCSSFlex, getActivePage, getPageCount, getPageSize, getPagingPosition, getSpan, isAutopaging, isPagingDisabled, isSizedByContent, isSpan, setAutopaging, setPagingDisabled, setPagingPosition, setSizedByContent, setSpan, setSpan
getContext, getCtrlKeys, getPopup, getPropertyAccess, getTooltip, setContext, setContext, setContextAttributes, setCtrlKeys, setPopup, setPopup, setPopupAttributes, setTooltip, setTooltip, setTooltipAttributes
addSclass, focus, getAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, removeSclass, removeSclass, setAction, setClass, setDraggable, setDroppable, setFocus, setHeight0, setHeightDirectly, setHflex, setHflex0, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTabindex, setTabindex, setTooltiptext, setTop, setTopDirectly, setVflex0, setVflexDirectly, setWidth, setWidth0, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly
addAnnotation, addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildRemoved, beforeParentChanged, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, enableBindingAnnotation, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getCallback, getChildren, getClientAttribute, getClientDataAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, invalidate, invalidatePartial, isChildable, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, replace, response, response, response, service, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setPage, setPageBefore, setParent, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetAttribute, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize
public void onPageAttached(org.zkoss.zk.ui.Page newpage, org.zkoss.zk.ui.Page oldpage)
onPageAttached
in interface org.zkoss.zk.ui.sys.ComponentCtrl
onPageAttached
in class org.zkoss.zk.ui.AbstractComponent
public void onPageDetached(org.zkoss.zk.ui.Page page)
onPageDetached
in interface org.zkoss.zk.ui.sys.ComponentCtrl
onPageDetached
in class org.zkoss.zk.ui.AbstractComponent
public boolean isVflex()
Default: false.
public void setVflex(boolean vflex)
public void setVflex(String flex)
setVflex
in class org.zkoss.zk.ui.HtmlBasedComponent
public void setFixedLayout(boolean fixedLayout)
MeshElement.setSizedByContent(boolean)
(!fixedLayout) insteadfixedLayout
- true to outline this grid by browserpublic boolean isFixedLayout()
MeshElement.isSizedByContent()
insteadpublic Rows getRows()
public Columns getColumns()
public Foot getFoot()
public Frozen getFrozen()
public Collection<org.zkoss.zk.ui.Component> getHeads()
getColumns()
and auxiliary heads (Auxhead
) (never null).public org.zkoss.zk.ui.Component getCell(int row, int col)
row
- which row to fetch (starting at 0).col
- which column to fetch (starting at 0).public String getAlign()
public void setAlign(String align)
public int getVisibleRows()
Default: 0.
public void setVisibleRows(int visibleRows) throws org.zkoss.zk.ui.WrongValueException
Note: Not allowed to set visibleRows and height/vflex at the same time
org.zkoss.zk.ui.WrongValueException
public void setHeight(String height)
setHeight
in class org.zkoss.zk.ui.HtmlBasedComponent
public Paginal getPaginal()
AbstractComponent.getMold()
is "paging".
If mold is "paging", this method never returns null, because
a child paging controller is created automatically (if not specified
by developers with setPaginal(org.zkoss.zul.ext.Paginal)
).
If a paging controller is specified (either by setPaginal(org.zkoss.zul.ext.Paginal)
,
or by setMold(java.lang.String)
with "paging"),
the grid will rely on the paging controller to handle long-content
instead of scrolling.
public void setPaginal(Paginal pgi)
AbstractComponent.getMold()
is "paging".
It is OK, though without any effect, to specify a paging controller even if mold is not "paging".
pgi
- the paging controller. If null and AbstractComponent.getMold()
is "paging",
a paging controller is created automatically as a child component
(see getPagingChild()
).public Paging getPagingChild()
setPaginal(org.zkoss.zul.ext.Paginal)
.protected Paginal pgi()
MeshElement
pgi
in class MeshElement
public <T> ListModel<T> getModel()
Note: if setModel(GroupsModel)
was called with a
groups model, this method returns an instance of ListModel
encapsulating it.
setModel(ListModel)
,
setModel(GroupsModel)
public <T> ListModel<T> getListModel()
GroupsModel
or not associated with any list data model.setModel(ListModel)
public <D,G,F> GroupsModel<D,G,F> getGroupsModel()
ListModel
or not associated with any list data model.setModel(GroupsModel)
public void setModel(ListModel<?> model)
model
- the list model to associate, or null to dissociate
any previous model.org.zkoss.zk.ui.UiException
- if failed to initialize with the modelgetListModel()
,
setModel(GroupsModel)
public void setModel(GroupsModel<?,?,?> model)
The groups model is used to represent a list of data with grouping.
model
- the groups model to associate, or null to dissociate
any previous model.org.zkoss.zk.ui.UiException
- if failed to initialize with the modelsetModel(ListModel)
,
getGroupsModel()
public <T> RowRenderer<T> getRowRenderer()
public void setRowRenderer(RowRenderer<?> renderer)
getModel()
is not null.
Note: changing a render will not cause the grid to re-render.
If you want it to re-render, you could assign the same model again
(i.e., setModel(getModel())), or fire an ListDataEvent
event.
renderer
- the renderer, or null to use the default.org.zkoss.zk.ui.UiException
- if failed to initialize with the modelpublic void setRowRenderer(String clsnm) throws ClassNotFoundException, NoSuchMethodException, IllegalAccessException, InstantiationException, InvocationTargetException
public int getPreloadSize()
Default: 50. (since 6.0.1)
It is used only if live data (setModel(ListModel)
and
not paging (getPagingChild()
.
Note: if the "pre-load-size" attribute of component is specified, it's prior to the original value.(@since 3.0.4)
public void setPreloadSize(int sz)
It is used only if live data (setModel(ListModel)
and
not paging (getPagingChild()
.
sz
- the number of rows to preload. If zero, no preload
at all.org.zkoss.zk.ui.UiException
- if sz is negativepublic void setInnerWidth(String innerWidth)
Application developers rarely call this method, unless
they want to preserve the widths of sizable columns
changed by the user.
To preserve the widths, the developer have to store the widths of
all columns and the inner width (getInnerWidth()
),
and then restore them when re-creating this component.
innerWidth
- the inner width. If null, "100%" is assumed.public String getInnerWidth()
Default: "100%"
setInnerWidth(java.lang.String)
public void onInitRender()
public void onPagingInitRender()
public void renderRow(Row row)
Row
if not loaded yet,
with getRowRenderer()
.
It does nothing if getModel()
returns null.
In other words, it is meaningful only if live data model is used.
public void renderAll()
Row
if not loaded yet,
with getRowRenderer()
.public void renderRows(Set<? extends Row> rows)
renderItems(java.util.Set<? extends org.zkoss.zul.Row>)
.public String getOddRowSclass()
Default: getZclass()
-odd. (since 3.5.0)
public void setOddRowSclass(String scls)
public void setMold(String mold)
setMold
in interface org.zkoss.zk.ui.Component
setMold
in class org.zkoss.zk.ui.AbstractComponent
mold
- the mold. If null or empty, "default" is assumed.
Allowed values: default, pagingComponentDefinition
public String getZclass()
getZclass
in class org.zkoss.zk.ui.HtmlBasedComponent
public void beforeChildAdded(org.zkoss.zk.ui.Component newChild, org.zkoss.zk.ui.Component refChild)
beforeChildAdded
in interface org.zkoss.zk.ui.sys.ComponentCtrl
beforeChildAdded
in class org.zkoss.zk.ui.AbstractComponent
public boolean insertBefore(org.zkoss.zk.ui.Component newChild, org.zkoss.zk.ui.Component refChild)
insertBefore
in interface org.zkoss.zk.ui.Component
insertBefore
in class org.zkoss.zk.ui.AbstractComponent
public boolean removeChild(org.zkoss.zk.ui.Component child)
removeChild
in interface org.zkoss.zk.ui.Component
removeChild
in class org.zkoss.zk.ui.AbstractComponent
protected boolean isAutohidePaging()
isAutohidePaging
in class MeshElement
public Object clone()
clone
in interface org.zkoss.zk.ui.Component
clone
in class XulElement
public String getEmptyMessage()
public void setEmptyMessage(String emptyMessage)
emptyMessage
- protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) throws IOException
renderProperties
in class MeshElement
IOException
public void sessionWillPassivate(org.zkoss.zk.ui.Page page)
sessionWillPassivate
in interface org.zkoss.zk.ui.sys.ComponentCtrl
sessionWillPassivate
in class org.zkoss.zk.ui.AbstractComponent
public void sessionDidActivate(org.zkoss.zk.ui.Page page)
sessionDidActivate
in interface org.zkoss.zk.ui.sys.ComponentCtrl
sessionDidActivate
in class org.zkoss.zk.ui.AbstractComponent
public Object getExtraCtrl()
getExtraCtrl
in interface org.zkoss.zk.ui.sys.ComponentCtrl
getExtraCtrl
in class org.zkoss.zk.ui.HtmlBasedComponent
public void service(org.zkoss.zk.au.AuRequest request, boolean everError)
Default: in addition to what are handled by HtmlBasedComponent.service(org.zkoss.zk.au.AuRequest, boolean)
,
it also handles onSelect.
service
in interface org.zkoss.zk.ui.sys.ComponentCtrl
service
in class org.zkoss.zk.ui.HtmlBasedComponent
public void setActivePage(int pg) throws org.zkoss.zk.ui.WrongValueException
MeshElement
setActivePage
in class MeshElement
org.zkoss.zk.ui.WrongValueException
public void setPageSize(int pgsz) throws org.zkoss.zk.ui.WrongValueException
MeshElement
setPageSize
in class MeshElement
org.zkoss.zk.ui.WrongValueException
public void onAfterRender()
public void scrollToIndex(int index)
index
- the index of rowCopyright © 2020. All rights reserved.