|
|
| Line 1: |
Line 1: |
| | {{ZKDevelopersGuidePageHeader}} | | {{ZKDevelopersGuidePageHeader}} |
| | | | |
| − | == Paging ==
| |
| − | A <tt>paging</tt> component is used to separate long content into multiple pages. For example, assume that you have 100 items and prefer to show 20 items at a time, you can use the <tt>paging</tt> components as follows.
| |
| | | | |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <paging totalSize="100" pageSize="20"/>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | When a user clicks the paging component, the <tt>onPaging</tt> event is sent along with an instance of <tt>org.zkoss.zul.event.PagingEvent</tt> to the <tt>paging</tt> component. To decide which portion of your 100 items are visible, you can add a listener to the <tt>paging</tt> component. Please note that the code below is pseudo code, you can find a real world example [http://docs.zkoss.org/wiki/Use_Load-On-Demand_to_Handle_Huge_Data here].
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <paging id="paging" />
| |
| − |
| |
| − | <zscript>
| |
| − | List result = new SearchEngine().find("ZK");
| |
| − | //assume SearchEngine.find() will return a list of items.
| |
| − |
| |
| − | paging.setTotalSize(result.size());
| |
| − | paging.addEventListener("onPaging", new org.zkoss.zk.ui.event.EventListener() {
| |
| − | public void onEvent(Event event) {
| |
| − | int pgno = event.getPaginal().getActivePage();
| |
| − | int ofs = pgno * event.getPaginal().getPageSize();
| |
| − |
| |
| − |
| |
| − | new Viewer().redraw(result, ofs, ofs + event.getPaginal().
| |
| − | getPageSize() - 1);
| |
| − | //assume redraw(List result, int b, int e) will display
| |
| − | //from the b-th item to the e-th item
| |
| − | }
| |
| − | }
| |
| − | );
| |
| − | </zscript>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | ===Paging supports OS mold.===
| |
| − |
| |
| − | For those who prefer the legacy layout of ZK 3.0』s Button component, please use OS mold as follows:
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <paging mold="os" totalSize="100" pageSize="10"/>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | [[Image:Paging2.png]]
| |
| − |
| |
| − | === Paging with List Boxes and Grids ===
| |
| − |
| |
| − | The <tt>listbox</tt> and <tt>grid</tt> component supports <tt>paging</tt> intrinsically, therefore you don't need to specify a <tt>paging</tt> component explicitly as above, unless you want to have different visual layout or to control multiple list boxes and grids with one <tt>paging</tt> component.
| |
| − |
| |
| − | Please refer to the <tt>Grids</tt> section for more details.
| |
| − |
| |
| − |
| |
| − | === Paging with Tree ===
| |
| − |
| |
| − | To use <tt>paging</tt> with <tt>trees</tt>, you have to set the <tt>mold="paging"</tt>. Related attributes <tt>pageSize</tt> and <tt>pagingPosition</tt> are optional.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <tree mold="paging" pageSize="4" pagingPosition="both">
| |
| − | </tree>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | == Tree Controls ==
| |
| − | Components: <tt>tree</tt>, <tt>treechildren</tt>, <tt>treeitem</tt>, <tt>treerow</tt>, <tt>treecell</tt>, <tt>treecols</tt> and <tt>treecol</tt>.
| |
| − |
| |
| − | A tree consists of two parts, the set of columns and the tree body. The set of columns is defined by the number of <tt>treecol</tt> components. Each column will appear as a header at the top of the tree. The second part, the tree body, contains the data to appear in the tree and is created using a <tt>treechildren</tt> component.
| |
| − |
| |
| − | An example of a tree control is as follows.
| |
| − |
| |
| − | [[Image:10000000000001E5000000727EE351E4.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <tree id="tree" rows="5">
| |
| − | <treecols>
| |
| − | <treecol label="Name"/>
| |
| − | <treecol label="Description"/>
| |
| − | </treecols>
| |
| − | <treechildren>
| |
| − | <treeitem>
| |
| − | <treerow>
| |
| − | <treecell label="Item 1"/>
| |
| − | <treecell label="Item 1 description"/>
| |
| − | </treerow>
| |
| − | </treeitem>
| |
| − | <treeitem>
| |
| − | <treerow>
| |
| − | <treecell label="Item 2"/>
| |
| − | <treecell label="Item 2 description"/>
| |
| − | </treerow>
| |
| − | <treechildren>
| |
| − | <treeitem>
| |
| − | <treerow>
| |
| − | <treecell label="Item 2.1"/>
| |
| − | </treerow>
| |
| − | <treechildren>
| |
| − | <treeitem>
| |
| − | <treerow>
| |
| − | <treecell label="Item 2.1.1"/>
| |
| − | </treerow>
| |
| − | </treeitem>
| |
| − | <treeitem>
| |
| − | <treerow>
| |
| − | <treecell label="Item 2.1.2"/>
| |
| − | </treerow>
| |
| − | </treeitem>
| |
| − | </treechildren>
| |
| − | </treeitem>
| |
| − | <treeitem>
| |
| − | <treerow>
| |
| − | <treecell label="Item 2.2"/>
| |
| − | <treecell label="Item 2.2 is something who cares"/>
| |
| − | </treerow>
| |
| − | </treeitem>
| |
| − | </treechildren>
| |
| − | </treeitem>
| |
| − | <treeitem label="Item 3"/>
| |
| − | </treechildren>
| |
| − | </tree>
| |
| − | </source>
| |
| − |
| |
| − | * <tt>tree</tt>: This is the outer component of a tree control.
| |
| − |
| |
| − | * <tt>treecols</tt>: This component is a placeholder for a collection of <tt>treecol</tt> components.
| |
| − |
| |
| − | * <tt>treecol</tt>: This is used to declare a column of the tree. By using this column, you can specify additional information such as the column header.
| |
| − |
| |
| − | * <tt>treechildren</tt>: This contains the main body of the tree, which contain a collection of <tt>treeitem</tt> components.
| |
| − | * <tt>treeitem</tt>: This component contains a row of data (<tt>treerow</tt>), and optionally <tt>treechildren</tt>.
| |
| − | ** If the component doesn't contain a <tt>treechildren</tt> component, it is a leaf node that doesn't accept any child items.
| |
| − | ** If it contains <tt>treechildren</tt>, it is a branch node that might contain other items.
| |
| − | ** For a branch node, a +/- button will appear at the beginning of the row, such that the user could open and close the item by clicking on the +/- button.
| |
| − | * <tt>treerow</tt>: A single row in the tree which needs to be placed inside a <tt>treeitem</tt> component.
| |
| − | * <tt>treecell</tt>: A single cell in a tree row which is placed inside a <tt>treerow</tt> component.
| |
| − |
| |
| − | '''Mouseless Entry <tt>tree'''</tt>
| |
| − |
| |
| − | * Press <tt>UP</tt> and <tt>DOWN</tt> to move the selection up and down by one tree item.
| |
| − | *Press <tt>PgUp</tt> and <tt>PgDn</tt> to move the selection up and down by one page.
| |
| − | * Press <tt>HOME</tt> to move the selection to the first item, and <tt>END</tt> to the last item.
| |
| − | * Press <tt>RIGHT</tt> to open a tree item, and <tt>LEFT</tt> to close a tree item.
| |
| − | *Press <tt>Ctrl+UP</tt> and <tt>Ctrl+DOWN</tt> to move the focus up and down by one tree item without changing the selection.
| |
| − | * Press <tt>SPACE</tt> to select the item in focus.
| |
| − |
| |
| − | === The open Property and the onOpen Event ===
| |
| − | Each tree item contains the <tt>open</tt> property which is used to control whether to display its』 child items. The default value is true. By setting this property to false, you are able to control what part of the tree is invisible.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <treeitem open="false">
| |
| − | </source>
| |
| − |
| |
| − | When a user clicks on the +/- button, he opens the tree item and makes its』 children visible. The <tt>onOpen</tt> event is then sent to the server to notify the application.
| |
| − |
| |
| − | For sophisticated applications, you can defer the creation of the content of the tree item or manipulate its content dynamically until the <tt>onOpen</tt> event is received. Refer to the '''Load on Demand''' section in the '''ZK User Interface Markup Language''' chapter for details.
| |
| − |
| |
| − | === Multiple Selection ===
| |
| − | When user clicks on a tree item, the whole item is selected and the <tt>onSelect</tt> event is sent back to the server to notify the application. You can control whether a tree control allows multiple selections by setting the <tt>multiple</tt> attribute to true. The default value is false.
| |
| − |
| |
| − | === Paging ===
| |
| − | [[Image:100000000000008A000001112B40E516.png]]
| |
| − |
| |
| − | The <tt>pageSize</tt> attribute controls the number of tree items to display at once. By default, it is 10. That is, at most 10 tree items are displayed client side for each level.
| |
| − |
| |
| − | A user can click to see more tree items (i.e., enlarge <tt>pageSize</tt>), or click to scroll up and down.
| |
| − |
| |
| − | If you want to display all the tree items, simply set the <tt>pageSize</tt> to -1. However, it is not recommended if the tree control is large as the browser is too slow to handle a tree with a large number of items.
| |
| − |
| |
| − | In addition to the <tt>pageSize</tt> attribute of a tree control, you can change the page size of each <tt>treechildren</tt> instance by modifying the <tt>treechildren』s</tt> <tt>pageSize</tt> property.
| |
| − |
| |
| − | '''Note:''' The function had deprecated as of release ZK 3.0.7. Please use the '''paging''' mold instead.
| |
| − |
| |
| − | ==== The onPaging and onPageSize Event ====
| |
| − | When a user clicks to scroll up and down the page, the <tt>onPaging</tt> event is sent along with a <tt>org.zkoss.zul.event.PagingEvent</tt> instance. Similarly, the <tt>onPageSize</tt> event is sent along with an <tt>org.zkoss.zul.event.PageSize</tt> instance.
| |
| − |
| |
| − | === Special Properties ===
| |
| − | ==== The rows Property ====
| |
| − | The <tt>rows</tt> attribute is used to control how many rows are visible. By setting it to zero, the tree control will resize itself to hold as many as items as possible.
| |
| − |
| |
| − | ==== The checkmark Property ====
| |
| − | [[Image:10000000000001980000007BBA791396.png]]
| |
| − |
| |
| − | The <tt>checkmark</tt> attribute controls whether to display a checkbox or a radio button in front of each tree item. If the <tt>multiple</tt> attribute is set to true and the <tt>checkmark</tt> is set to true then a checkbox will be displayed in front of every item. However, if <tt>multiple</tt> is set to false then a radio button will be displayed instead.
| |
| − |
| |
| − | ==== The vflex Property ====
| |
| − | The <tt>vflex</tt> attribute controls whether to grow or shrink vertically to fit their given space. It is so-called vertical flexibility. For example, if the tree is too big to fit in the browser window, it will shrink to make the whole tree visible in the browser window.
| |
| − |
| |
| − | This property is ignored if the <tt>rows</tt> attribute is specified.
| |
| − |
| |
| − | ==== The maxlength Property ====
| |
| − | The <tt>maxlength</tt> attribute defines the maximal allowed characters being visible at the browser. By setting this property, you can make a narrower tree control.
| |
| − |
| |
| − | ==== Sizable Columns ====
| |
| − | Like <tt>columns</tt>, you can set the <tt>sizable</tt> attribute of <tt>treecols</tt> to <tt>true</tt> in order to allow users to resize the width of the tree headers. Similarly, the <tt>onColSize</tt> event is sent when a user resizes the widths.
| |
| − |
| |
| − | === Create-on-Open for Tree Controls ===
| |
| − | As illustrated below, you could listen to the <tt>onOpen</tt> event, and then load the children of a tree item. You can do the same thing using group boxes.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <tree width="200px">
| |
| − | <treecols>
| |
| − | <treecol label="Subject"/>
| |
| − | <treecol label="From"/>
| |
| − | </treecols>
| |
| − | <treechildren>
| |
| − | <treeitem open="false" onOpen="load()">
| |
| − | <treerow>
| |
| − | <treecell label="Intel Snares XML"/>
| |
| − | <treecell label="David Needle"/>
| |
| − | </treerow>
| |
| − | <treechildren/>
| |
| − | </treeitem>
| |
| − | </treechildren>
| |
| − | <zscript>
| |
| − | void load() {
| |
| − | Treechildren tc = self.getTreechildren();
| |
| − | if (tc.getChildren().isEmpty()) {
| |
| − | Treeitem ti = new Treeitem();
| |
| − | ti.setLabel("New added");
| |
| − | ti.setParent(tc);
| |
| − | }
| |
| − | }
| |
| − | </zscript>
| |
| − | </tree>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | == Grids ==
| |
| − | Components: <tt>grid</tt>, <tt>columns</tt>, <tt>column</tt>, <tt>rows</tt> and <tt>row</tt>.
| |
| − |
| |
| − | A grid contains components that are aligned in rows like tables. Inside a grid, you declare two things, the columns and the rows. Within the columns you define the header and the column attributes and then provide the row content.
| |
| − |
| |
| − | To declare row data use the <tt>rows</tt> component which is a child element of <tt>grid</tt>. Inside that you should add <tt>row</tt> components, which are used for each row. Inside the row element, you should place the content that you want inside that row. Each child is a column of the specific row.
| |
| − |
| |
| − | Similarly, the columns are declared with the <tt>columns</tt> component, which should be a child element of <tt>grid</tt>. <tt>column</tt> declares the common attributes of each column, such as the width and alignment, and optional headers, i.e., label and/or image.
| |
| − |
| |
| − | [[Image:100000000000017D0000004DD592B1C3.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <grid>
| |
| − | <columns>
| |
| − | <column label="Type"/>
| |
| − | <column label="Content"/>
| |
| − | </columns>
| |
| − | <rows>
| |
| − | <row>
| |
| − | <label value="File:"/>
| |
| − | <textbox width="99%"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Type:"/>
| |
| − | <hbox>
| |
| − | <listbox rows="1" mold="select">
| |
| − | <listitem label="Java Files,(*.java)"/>
| |
| − | <listitem label="All Files,(*.*)"/>
| |
| − | </listbox>
| |
| − | <button label="Browse..."/>
| |
| − | </hbox>
| |
| − | </row>
| |
| − | </rows>
| |
| − | </grid>
| |
| − | </source>
| |
| − |
| |
| − | === Scrollable Grid ===
| |
| − | [[Image:10000000000001FC0000009FFC9DC218.png]]
| |
| − |
| |
| − | A grid can be scrollable if you specify the <tt>height</tt> attribute and there is not enough space to display all data.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <grid width="500px" height="130px">
| |
| − | <columns>
| |
| − | <column label="Head 1"/>
| |
| − | <column label="Head 2" align="center"/>
| |
| − | <column label="Head 3" align="right"/>
| |
| − | </columns>
| |
| − | <rows>
| |
| − | <row>
| |
| − | <listbox mold="select">
| |
| − | <listitem label="Faster"/>
| |
| − | <listitem label="Fast"/>
| |
| − | <listitem label="Average"/>
| |
| − | </listbox>
| |
| − | <datebox/>
| |
| − | <textbox rows="2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <checkbox checked="true" label="Option 1"/>
| |
| − | <checkbox label="Option 2"/>
| |
| − | <radiogroup>
| |
| − | <radio label="Apple"/>
| |
| − | <radio label="Orange" checked="true"/>
| |
| − | <radio label="Lemon"/>
| |
| − | </radiogroup>
| |
| − | </row>
| |
| − | <row>
| |
| − | <checkbox checked="true" label="Option 1"/>
| |
| − | <checkbox label="Option 2"/>
| |
| − | <radiogroup orient="vertical">
| |
| − | <radio label="Apple"/>
| |
| − | <radio label="Orange" checked="true"/>
| |
| − | <radio label="Lemon"/>
| |
| − | </radiogroup>
| |
| − | </row>
| |
| − | </rows>
| |
| − | </grid>
| |
| − | </source>
| |
| − |
| |
| − | === Sizable Columns ===
| |
| − | If you allow users to resize the width of your columns, you can set the <tt>sizable</tt> attribute of your columns as <tt>true</tt>. Once allowed, users can resize the widths of columns by dragging the border between adjacent <tt>column</tt> components.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <window>
| |
| − | <grid>
| |
| − | <columns id="cs" sizable="true">
| |
| − | <column label="AA"/>
| |
| − | <column label="BB"/>
| |
| − | <column label="CC"/>
| |
| − | </columns>
| |
| − | <rows>
| |
| − | <row>
| |
| − | <label value="AA01"/>
| |
| − | <label value="BB01"/>
| |
| − | <label value="CC01"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="AA01"/>
| |
| − | <label value="BB01"/>
| |
| − | <label value="CC01"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="AA01"/>
| |
| − | <label value="BB01"/>
| |
| − | <label value="CC01"/>
| |
| − | </row>
| |
| − | </rows>
| |
| − | </grid>
| |
| − | <checkbox label="sizeable" checked="true" onCheck="cs.sizeable = self.checked"/>
| |
| − | </window>
| |
| − | </source>
| |
| − |
| |
| − | ==== The onColSize Event ====
| |
| − | Once a user resizes the width, the <tt>onColSize</tt> event is sent with an instance of <tt>org.zkoss.zul.event.ColSizeEvent</tt>. Notice that the column's width is adjusted before the<tt> onColSize</tt> event is sent. In other words, the event serves as a notification that you can ignore. Of course, you can do whatever you want in the event listener.
| |
| − |
| |
| − | === Grids with Paging ===
| |
| − | There are two ways to handle large content in a grid, scrolling and paging. Scrolling is enabled by setting the <tt>height</tt> attribute as discussed in the previous section. Paging is enabled by setting the <tt>mold</tt> attribute to <tt>paging</tt>. Once paging is enabled, the grid separates the content into several pages and displays one page at a time as depicted below.
| |
| − |
| |
| − | [[Image:1000000000000133000000737A37B110.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <grid width="300px" mold="paging" pageSize="4">
| |
| − | <columns>
| |
| − | <column label="Left"/>
| |
| − | <column label="Right"/>
| |
| − | </columns>
| |
| − | <rows>
| |
| − | <row>
| |
| − | <label value="Item 1.1"/><label value="Item 1.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item 2.1"/><label value="Item 2.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item 3.1"/><label value="Item 3.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item 4.1"/><label value="Item 4.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item 5.1"/><label value="Item 5.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item 6.1"/><label value="Item 6.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item 7.1"/><label value="Item 7.2"/>
| |
| − | </row>
| |
| − | </rows>
| |
| − | </grid>
| |
| − | </source>
| |
| − |
| |
| − | Once the paging mold is set, the grid creates an instance of the <tt>paging</tt> component '''as a child of the grid''' and the paging component in turn handles the grid』s paging. Therefore, the number of the <tt>grid』s</tt> children includes the paging component. Also, if you remove all children of the <tt>grid</tt>, the <tt>paging</tt> is also removed.
| |
| − |
| |
| − | ==== The pageSize Property ====
| |
| − | Having set the <tt>paging</tt> mold, you can specify how many rows are visible at a time (i.e., the page size) by setting the <tt>pageSize</tt> attribute to a numeric value. By default, it is 20.
| |
| − |
| |
| − | ==== The paginal Property ====
| |
| − | If you prefer to place the <tt>paging</tt> component in a different location or you want to control two or more grids with the same <tt>paging</tt> component, you can assign the <tt>paginal</tt> attribute explicitly. Note: if it is not set explicitly, it is the same as the <tt>paging</tt> property.
| |
| − |
| |
| − | [[Image:100000000000026C00000066A82ED1BB.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <vbox>
| |
| − | <paging id="pg" pageSize="4"/>
| |
| − | <hbox>
| |
| − | <grid width="300px" mold="paging" paginal="${pg}">
| |
| − | <columns>
| |
| − | <column label="Left"/><column label="Right"/>
| |
| − | </columns>
| |
| − | <rows>
| |
| − | <row>
| |
| − | <label value="Item 1.1"/><label value="Item 1.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item 2.1"/><label value="Item 2.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item 3.1"/><label value="Item 3.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item 4.1"/><label value="Item 4.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item 5.1"/><label value="Item 5.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item 6.1"/><label value="Item 6.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item 7.1"/><label value="Item 7.2"/>
| |
| − | </row>
| |
| − | </rows>
| |
| − | </grid>
| |
| − | <grid width="300px" mold="paging" paginal="${pg}">
| |
| − | <columns>
| |
| − | <column label="Left"/><column label="Right"/>
| |
| − | </columns>
| |
| − | <rows>
| |
| − | <row>
| |
| − | <label value="Item A.1"/><label value="Item A.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item B.1"/><label value="Item B.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item C.1"/><label value="Item C.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item D.1"/><label value="Item D.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item E.1"/><label value="Item E.2"/>
| |
| − | </row>
| |
| − | <row>
| |
| − | <label value="Item F.1"/><label value="Item F.2"/>
| |
| − | </row>
| |
| − | </rows>
| |
| − | </grid>
| |
| − | </hbox>
| |
| − | </vbox>
| |
| − | </source>
| |
| − |
| |
| − | ==== The paging Property ====
| |
| − | It is a read-only attribute representing the child <tt>paging</tt> component that is created automatically. It is null if you assign external paging via the <tt>paginal</tt> attribute. You rarely need to access this attribute as it is generally better to use the <tt>paginal</tt> attribute.
| |
| − |
| |
| − | ==== The onPaging Event and Method ====
| |
| − | Once a user clicks the page number of the <tt>paging</tt> component, an <tt>onPaging</tt> event is sent the grid. It is then processed by the <tt>onPaging</tt> method. By default, the method invalidates, i.e., redraws, the content of <tt>rows</tt>.
| |
| − |
| |
| − | If you want to implement "create-on-demand" feature, you can add a event listener to the grid for the <tt>onPaging</tt> event. The line below demonstrates how to add an EventListener.
| |
| − |
| |
| − | <source lang="java" >
| |
| − | grid.addEventListener(org.zkoss.zul.event.ZulEvents.ON_PAGING, new MyListener());
| |
| − | </source>
| |
| − |
| |
| − | === Sorting ===
| |
| − | Grids support the direct sorting of rows. To enable ascending order sorting for a particular column, you need to assign a <tt>java.util.Comparator</tt> instance to the <tt>sortAscending</tt> attribute of the column. Similarly, you assign a comparator to the <tt>sortDescending</tt> property to enable the descending order.
| |
| − |
| |
| − | As illustrated below, you first implement a comparator that compares any two rows of the grid, and then assign its instances to the <tt>sortAscending</tt> and/or <tt>sortDescending</tt> attributes. Notice: the <tt>compare</tt> method is passed two <tt>org.zkoss.zul.Row</tt> instances.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <zscript>
| |
| − | class MyRowComparator implements Comparator {
| |
| − | public MyRowComparator(boolean ascending) {
| |
| − | ...
| |
| − | }
| |
| − | public int compare(Object o1, Object o2) {
| |
| − | Row r1 = (Row)o1, r2 = (Row)o2;
| |
| − | ....
| |
| − | }
| |
| − | }
| |
| − | Comparator asc = new MyRowComparator(true);
| |
| − | Comparator dsc = new MyRowComparator(false);
| |
| − | </zscript>
| |
| − | <grid>
| |
| − | <columns>
| |
| − | <column sortAscending="${asc}" sortDescending="${dsc}"/>
| |
| − | ...
| |
| − | </source>
| |
| − |
| |
| − | ==== The sortDirection Property ====
| |
| − | The <tt>sortDirection</tt> property controls whether to show an icon to indicate the order of a particular column. If rows are sorted before being added to the grid, you should set this property explicitly.
| |
| − |
| |
| − | <column sortDirection="ascending"/>
| |
| − |
| |
| − | It is then maintained automatically by the grid as long as you assign the comparators to the corresponding column.
| |
| − |
| |
| − | ==== The onSort Event ====
| |
| − | When you assign at least one comparator to a column, an <tt>onSort</tt> event is sent to the server if user clicks on it. The <tt>column</tt> component implements a listener to automatically sort rows based on the assigned comparator.
| |
| − |
| |
| − | If you prefer to handle this manually, you can add your own listener to the column for the <tt>onSort</tt> event. To prevent the default listener to invoking the <tt>sort</tt> method, you have to call the <tt>stopPropagation</tt> method for the event being received. Alternatively, you can override the <tt>sort</tt> method, see below.
| |
| − |
| |
| − | ==== The sort Method ====
| |
| − | The <tt>sort</tt> method is the underlying implementation of the default <tt>onSort</tt> event listener. It is also useful if you want to sort the rows using Java code. For example, you might have to call this method after adding rows (assuming they not in the proper order).
| |
| − |
| |
| − | <source lang="java" >
| |
| − | Row row = new Row();
| |
| − | row.setParent(rows);
| |
| − | row.appendChild(...);
| |
| − | ...
| |
| − | if (!"natural".column.getSortDirection())
| |
| − | column.sort("ascending".equals(column.getSortDirection()));
| |
| − | </source>
| |
| − |
| |
| − | The default sorting algorithm is quick-sort (by use of the <tt>sort</tt> method from the <tt>org.zkoss.zk.ui.Components</tt> class). You can override it with your own implementation.
| |
| − |
| |
| − | Note: the <tt>sort</tt> method checks the sort direction (by calling <tt>getSortDirection</tt>). It sorts the rows only if the sort direction is different. To enforce the sorting, do as follows.
| |
| − |
| |
| − | <source lang="java" >
| |
| − | column.setSortDirection("natural");
| |
| − | sort(myorder);
| |
| − | </source>
| |
| − |
| |
| − | The above code is equivalent to the following.
| |
| − |
| |
| − | <source lang="java" >
| |
| − | sort(myorder, true);
| |
| − | </source>
| |
| − |
| |
| − | <font color="red">Update: </font> see more about sorting [[Multiple Field Sorting on Listbox]].
| |
| − |
| |
| − | === Live Data ===
| |
| − | Like list boxes, grids support ''live data''. With live data, developers are able to separate the data from the view. In other words, developers only need to provide the data by implementing the <tt>org.zkoss.zul.ListModel</tt> interface, rather than manipulating the grid directly. The benefits are twofold.
| |
| − |
| |
| − | * It is easier to use different views to show the same set of data.
| |
| − | * The grid sends the data to the client only if it is visible. It saves a lot of network traffic if the amount of data is large.
| |
| − |
| |
| − | There are three steps to make use of live data.
| |
| − |
| |
| − | 1 Prepare the data in the form of a <tt>ListModel</tt>. ZK has a concrete implementation called <tt>org.zkoss.zul.SimpleListModel</tt> for representing an array of objects.
| |
| − | 2 Implement the <tt>org.zkoss.zul.RowRenderer</tt> interface for rendering a row of data into the grid.
| |
| − |
| |
| − | ** This is optional. If it is not specified the default renderer is used to render the data into the first column.
| |
| − | ** You can implement different renderers for representing the same data in different views.
| |
| − |
| |
| − | 3 Set the data in the <tt>model</tt> attribute and, optionally, the renderer in the <tt>rowRenderer</tt> attribute.
| |
| − |
| |
| − | In the following example, we prepared a list model called <tt>strset</tt>, assign it to a grid using the <tt>model</tt> attribute. Then, the grid will do the rest.
| |
| − |
| |
| − | [[Image:100000000000006900000083A11BBF49.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <window title="Live Grid" border="normal">
| |
| − | <zscript>
| |
| − | String[] data = new String[30];
| |
| − | for(int j=0; j < data.length; ++j) {
| |
| − | data[j] = "option "+j;
| |
| − | }
| |
| − | ListModel strset = new SimpleListModel(data);
| |
| − | </zscript>
| |
| − | <grid width="100px" height="100px" model="${strset}">
| |
| − | <columns>
| |
| − | <column label="options"/>
| |
| − | </columns>
| |
| − | </grid>
| |
| − | </window>
| |
| − | </source>
| |
| − |
| |
| − | ==== Sorting with Live Data ====
| |
| − | If you allow users to sort a grid with live data, you have to implement the interface, <tt>org.zkoss.zul.ListModelExt</tt>, in addition to the <tt>org.zkoss.zul.ListModel</tt>.
| |
| − |
| |
| − | <source lang="java" >
| |
| − | class MyListModel implements ListModel, ListModelExt {
| |
| − | public void sort(Comparator cmpr, boolean ascending) {
| |
| − | //do the real sorting
| |
| − | //notify the grid (or listbox) that data is changed by use of ListDataEvent
| |
| − | }
| |
| − | }
| |
| − | </source>
| |
| − |
| |
| − | When a user wants to sort the grid, the grid will invoke the <tt>sort</tt> method of <tt>ListModelExt</tt> to sort the data. In other words, the sorting is done by the list model, rather than the grid.
| |
| − |
| |
| − | After sorting, the list model will notify the grid by invoking the <tt>onChange</tt> method of the grid』s registered <tt>org.zkoss.zul.event.ListDataListener</tt> instances. These are registered by the <tt>addListDataListener</tt> method. In most cases, all the data is changed, so the list model usually sends the following event:
| |
| − |
| |
| − | <source lang="java" >
| |
| − | new ListDataEvent(this, ListDataEvent.CONTENTS_CHANGED, -1, -1)
| |
| − | </source>
| |
| − |
| |
| − | === Auxiliary Headers ===
| |
| − | In addition to columns, you can specify auxiliary headers with the <tt>auxhead</tt> and <tt>auxheader</tt> components as follows.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <grid>
| |
| − | <auxhead>
| |
| − | <auxheader label="H1'07" colspan="6"/>
| |
| − | <auxheader label="H2'07" colspan="6"/>
| |
| − | </auxhead>
| |
| − | <auxhead>
| |
| − | <auxheader label="Q1" colspan="3"/>
| |
| − | <auxheader label="Q2" colspan="3"/>
| |
| − | <auxheader label="Q3" colspan="3"/>
| |
| − | <auxheader label="Q4" colspan="3"/>
| |
| − | </auxhead>
| |
| − | <columns>
| |
| − | <column label="Jan"/><column label="Feb"/><column label="Mar"/>
| |
| − | <column label="Apr"/><column label="May"/><column label="Jun"/>
| |
| − | <column label="Jul"/><column label="Aug"/><column label="Sep"/>
| |
| − | <column label="Oct"/><column label="Nov"/><column label="Dec"/>
| |
| − | </columns>
| |
| − | <rows>
| |
| − | <row>
| |
| − | <label value="1,000"/><label value="1,100"/><label value="1,200"/>
| |
| − | <label value="1,300"/><label value="1,400"/><label value="1,500"/>
| |
| − | <label value="1,600"/><label value="1,700"/><label value="1,800"/>
| |
| − | <label value="1,900"/><label value="2,000"/><label value="2,100"/>
| |
| − | </row>
| |
| − | </rows>
| |
| − | </grid>
| |
| − | </source>
| |
| − |
| |
| − | [[Image:1000000000000235000000602BB4CFD2.png]]
| |
| − |
| |
| − | The auxiliary headers support the <tt>colspan</tt> and <tt>rowsspan</tt> attributes that the column header don't. However, as its』 name suggests, the auxiliary headers must be placed within a <tt>column</tt>.
| |
| − |
| |
| − | Unlike <tt>column</tt>/<tt>columns</tt>, which can only be used with <tt>grid</tt>, <tt>auhead</tt>/<tt>auxheader</tt> can be used with <tt>grid</tt>, <tt>listbox</tt> and <tt>tree</tt>.
| |
| − |
| |
| − | === Special Properties ===
| |
| − | ==== The spans Property ====
| |
| − | It is a list of comma separated integers, controlling whether to span a cell over several columns. The first number in the list denotes the number of columns the first cell shall span. The second number denotes the number of columns the second cell will span and so on. If a number is omitted, 1 is assumed.
| |
| − |
| |
| − | For example,
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <grid>
| |
| − | <columns>
| |
| − | <column label="Left" align="left"/><column label="Center" align="center"/>
| |
| − | <column label="Right" align="right"/><column label="Column 4"/>
| |
| − | <column label="Column 5"/><column label="Column 6"/>
| |
| − | </columns>
| |
| − | <rows>
| |
| − | <row>
| |
| − | <label value="Item A.1"/><label value="Item A.2"/>
| |
| − | <label value="Item A.3"/><label value="Item A.4"/>
| |
| − | <label value="Item A.5"/><label value="Item A.6"/>
| |
| − | </row>
| |
| − | <row spans="1,2,2">
| |
| − | <label value="Item B.1"/><label value="Item B.2"/>
| |
| − | <label value="Item B.4"/><label value="Item B.6"/>
| |
| − | </row>
| |
| − | <row spans="3">
| |
| − | <label value="Item C.1"/><label value="Item C.4"/>
| |
| − | <label value="Item C.5"/><label value="Item C.6"/>
| |
| − | </row>
| |
| − | <row spans=",,2,2">
| |
| − | <label value="Item D.1"/><label value="Item D.2"/>
| |
| − | <label value="Item D.3"/><label value="Item D.5"/>
| |
| − | </row>
| |
| − | </rows>
| |
| − | </grid>
| |
| − | </source>
| |
| − |
| |
| − | == List Boxes ==
| |
| − | Components: <tt>listbox</tt>, <tt>listitem</tt>, <tt>listcell</tt>, <tt>listhead</tt> and <tt>listheader</tt>.
| |
| − |
| |
| − | A list box is used to display a number of items in a list. The user may select an item from the list.
| |
| − |
| |
| − | The simplest format is as follows. It is a single-column and single-selection list box.
| |
| − |
| |
| − | [[Image:100000000000007A0000002F3C489432.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <listbox>
| |
| − | <listitem label="Butter Pecan"/>
| |
| − | <listitem label="Chocolate Chip"/>
| |
| − | <listitem label="Raspberry Ripple"/>
| |
| − | </listbox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | The Listbox has two molds: <tt>default</tt> and <tt>select</tt>. If the <tt>select</tt> mold is used, the HTML's <tt>SELECT</tt> tag is generated instead.
| |
| − |
| |
| − | [[Image:1000000000000085000000343B08C7D1.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <listbox mold="select">...</listbox>
| |
| − | </source>
| |
| − |
| |
| − | Note: if the <tt>mold</tt> is "<tt>select</tt>", <tt>rows</tt> is "1", and none of the items are marked as selected, the browser will display the <tt>listbox</tt> as if the first item is selected. Worst of all, if user selects the first item in this case, no <tt>onSelect</tt> event is sent. To avoid this confusion, developers should select at least one item when using <tt>mold="select"</tt> and <tt>rows="1"</tt>.
| |
| − |
| |
| − | In addition to each item』s label, you can assign an application-specific value to each item using the <tt>setValue</tt> method.
| |
| − |
| |
| − | '''Mouseless Entry <tt>listbox'''</tt>
| |
| − |
| |
| − | *Press <tt>UP</tt> and <tt>DOWN</tt> to move the selection up and down by one list item.
| |
| − | * Press <tt>PgUp</tt> and <tt>PgDn</tt> to move the selection up and down by one page.
| |
| − | * Press <tt>HOME</tt> to move the selection to the first item, and <tt>END</tt> to move to the last item.
| |
| − | * Press <tt>Ctrl+UP</tt> and <tt>Ctrl+DOWN</tt> to move the focus up and down by one list item without changing the selection.
| |
| − | * Press <tt>SPACE</tt> to select the item in focus.
| |
| − |
| |
| − | === Multi-Column List Boxes ===
| |
| − | The list box also supports multiple columns. When a user selects an item, the entire row is selected.
| |
| − |
| |
| − | To define a multi-column list, the number of listcells must match the number of columns with a row. For example if there are 4 columns then each row must contain 4 listcells.
| |
| − |
| |
| − | [[Image:10000000000000D10000002C2459185A.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <listbox width="200px">
| |
| − | <listitem>
| |
| − | <listcell label="George"/>
| |
| − | <listcell label="House Painter"/>
| |
| − | </listitem>
| |
| − | <listitem>
| |
| − | <listcell label="Mary Ellen"/>
| |
| − | <listcell label="Candle Maker"/>
| |
| − | </listitem>
| |
| − | <listitem>
| |
| − | <listcell label="Roger"/>
| |
| − | <listcell label="Swashbuckler"/>
| |
| − | </listitem>
| |
| − | </listbox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | === Column Headers ===
| |
| − | You can specify column headers by using <tt>listhead</tt> and <tt>listheader</tt>, please see the code below<ref name="ftn40">This feature is a bit different from XUL, where listhead and listheader are used.</ref>. In addition to label, you can specify an image as the header by use of the <tt>image</tt> attribute.
| |
| − |
| |
| − | [[Image:10000000000000D00000003725942D16.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <listbox width="200px">
| |
| − | <listhead>
| |
| − | <listheader label="Name"/>
| |
| − | <listheader label="Occupation"/>
| |
| − | </listhead>
| |
| − |
| |
| − | ...
| |
| − |
| |
| − | </listbox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | === Column Footers ===
| |
| − | You could specify the column footers by using <tt>listfoot</tt> and <tt>listfooter</tt>. Please note, each time a <tt>listhead</tt> instance is added to a list box, it must be the first child, and a <tt>listfoot</tt> instance the last child.
| |
| − |
| |
| − | [[Image:10000000000000D00000006D18232918.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <listbox width="200px">
| |
| − | <listhead>
| |
| − | <listheader label="Population"/>
| |
| − | <listheader align="right" label="%"/>
| |
| − | </listhead>
| |
| − | <listitem id="a" value="A">
| |
| − | <listcell label="A. Graduate"/>
| |
| − | <listcell label="20%"/>
| |
| − | </listitem>
| |
| − | <listitem id="b" value="B">
| |
| − | <listcell label="B. College"/>
| |
| − | <listcell label="23%"/>
| |
| − | </listitem>
| |
| − | <listitem id="c" value="C">
| |
| − | <listcell label="C. High School"/>
| |
| − | <listcell label="40%"/>
| |
| − | </listitem>
| |
| − | <listitem id="d" value="D">
| |
| − | <listcell label="D. Others"/>
| |
| − | <listcell label="17%"/>
| |
| − | </listitem>
| |
| − | <listfoot>
| |
| − | <listfooter label="More or less"/>
| |
| − | <listfooter label="100%"/>
| |
| − | </listfoot>
| |
| − | </listbox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | === Drop-Down List ===
| |
| − | You can create a drop-down list by setting the listbox』s mold to select and making the box a single row. Notice you cannot use multi-column for the drop-down list.
| |
| − |
| |
| − | [[Image:1000000000000049000000488DCF4463.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <listbox mold="select" rows="1">
| |
| − | <listitem label="Car"/>
| |
| − | <listitem label="Taxi"/>
| |
| − | <listitem label="Bus" selected="true"/>
| |
| − | <listitem label="Train"/>
| |
| − | </listbox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | === Multiple Selection ===
| |
| − | When a user clicks on a list item, the whole row is selected and the <tt>onSelect</tt> event is sent back to the server to notify the application. You are able to control whether a list box allows multiple selections by setting the <tt>multiple</tt> attribute to true. The default value is false.
| |
| − |
| |
| − | === Scrollable List Boxes ===
| |
| − | A list box will be scrollable if you specify the <tt>rows</tt> attribute or the <tt>height</tt> attribute and there is not enough space to display all list items.
| |
| − |
| |
| − | [[Image:10000000000001010000005ED2DEF030.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <listbox width="250px" rows="4">
| |
| − | <listhead>
| |
| − | <listheader label="Name" sort="auto"/>
| |
| − | <listheader label="Gender" sort="auto"/>
| |
| − | </listhead>
| |
| − | <listitem>
| |
| − | <listcell label="Mary"/>
| |
| − | <listcell label="FEMALE"/>
| |
| − | </listitem>
| |
| − | <listitem>
| |
| − | <listcell label="John"/>
| |
| − | <listcell label="MALE"/>
| |
| − | </listitem>
| |
| − | <listitem>
| |
| − | <listcell label="Jane"/>
| |
| − | <listcell label="FEMALE"/>
| |
| − | </listitem>
| |
| − | <listitem>
| |
| − | <listcell label="Henry"/>
| |
| − | <listcell label="MALE"/>
| |
| − | </listitem>
| |
| − | <listitem>
| |
| − | <listcell label="Michelle"/>
| |
| − | <listcell label="FEMALE"/>
| |
| − | </listitem>
| |
| − | </listbox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | ==== The rows Property ====
| |
| − | The <tt>rows</tt> attribute is used to control how many rows are visible. By setting it to zero, the list box will resize itself to hold as many as items if possible.
| |
| − |
| |
| − | === Sizable List Headers ===
| |
| − | Like <tt>columns</tt>, you can set the <tt>sizable</tt> attribute of the <tt>listhead</tt> to <tt>true</tt> to allow users to resize the width of list headers. The <tt>onColSize</tt> event is also sent when a user resizes listbox.
| |
| − |
| |
| − | === List Boxes with Paging ===
| |
| − | Like grids, you can use multiple pages to represent large content by setting the mold to <tt>paging</tt>. Similarly, you can control how many items each page displays, whether to use an external paging component and whether to customize the behavior when a page is selected. Please refer to the '''Grids''' section for more details.
| |
| − |
| |
| − | === Sorting ===
| |
| − | List boxes support sorting of list items directly. There are a few ways to enable the sorting of a particular column. The simplest way is to set the <tt>sort</tt> attribute of the list header to <tt>auto</tt> as demonstrated by the code below. Then, the column that the list header is associated with is sort-able based on the label of each list cell of the that column.
| |
| − |
| |
| − | [[Image:10000000000000CF0000005D419F9D95.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <listbox width="200px">
| |
| − | <listhead>
| |
| − | <listheader label="name" sort="auto"/>
| |
| − | <listheader label="gender" sort="auto"/>
| |
| − | </listhead>
| |
| − | <listitem>
| |
| − | <listcell label="Mary"/>
| |
| − | <listcell label="FEMALE"/>
| |
| − | </listitem>
| |
| − | <listitem>
| |
| − | <listcell label="John"/>
| |
| − | <listcell label="MALE"/>
| |
| − | </listitem>
| |
| − | <listitem>
| |
| − | <listcell label="Jane"/>
| |
| − | <listcell label="FEMALE"/>
| |
| − | </listitem>
| |
| − | <listitem>
| |
| − | <listcell label="Henry"/>
| |
| − | <listcell label="MALE"/>
| |
| − | </listitem>
| |
| − | </listbox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | ==== The sortAscending and sortDescending Properties ====
| |
| − | If you prefer to sort list items in different ways, you can assign a <tt>java.util.Comparator</tt> instance to the <tt>sortAscending</tt> and/or <tt>sortDescending</tt> attributes. Once assigned, the list items can be sorted in the ascending and/or descending order with the specified comparator.
| |
| − |
| |
| − | The invocation of the <tt>sort</tt> attribute with <tt>auto</tt> automatically assigns two comparators to the <tt>sortAscending</tt> and <tt>sortDescending</tt> attributes. You can override any of them by assigning another comparator.
| |
| − |
| |
| − | For example, assume you want to sort based on the value of list items, rather than list cell's label, then you assign an instance of <tt>ListitemComparator</tt> to these attributes as follows.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zscript>
| |
| − | Comparator asc = new ListitemComarator(-1, true, true);
| |
| − | Comparator dsc = new ListitemComarator(-1, false, true);
| |
| − | </zscript>
| |
| − | <listbox>
| |
| − | <listhead>
| |
| − | <listheader sortAscending="${asc}" sortDescending="${dsc}"/>
| |
| − | ...
| |
| − | </source>
| |
| − |
| |
| − | ==== The sortDirection Property ====
| |
| − | The <tt>sortDirection</tt> attribute controls whether to display an icon to indicate the order of a particular column. If list items are sorted before adding to the list box, you should set this attribute explicitly.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <listheader sortDirection="ascending"/>
| |
| − | </source>
| |
| − |
| |
| − | The sorting is maintained automatically by the listboxes as long as you assign the comparator to the corresponding list header.
| |
| − |
| |
| − | ==== The onSort Event ====
| |
| − | When you assign at least one comparator to a list header, an <tt>onSort</tt> event is sent to the server if user clicks on it. The list header implements a listener to automatically the sorting.
| |
| − |
| |
| − | If you prefer to handle this manually, you can add your own listener to the list header for the <tt>onSort</tt> event. To prevent the default listener invoking the <tt>sort</tt> method, you have to call the <tt>stopPropagation</tt> method. Alternatively, you can override the <tt>sort</tt> method, please see below.
| |
| − |
| |
| − | ==== The sort Method ====
| |
| − | The <tt>sort</tt> method is the underlying implementation of the default <tt>onSort</tt> event listener. It is also useful if you want to sort the list items using Java code. For example, you may have to call this method after adding items (assuming that they are not added in the proper order).
| |
| − |
| |
| − | <source lang="java" >
| |
| − | new Listem("New Stuff").setParent(listbox);
| |
| − | if (!"natural".header.getSortDirection())
| |
| − | header.sort("ascending".equals(header.getSortDirection()));
| |
| − | </source>
| |
| − |
| |
| − | The default sorting algorithm is quick-sort (by use of the <tt>sort</tt> method from the <tt>org.zkoss.zk.ui.Components</tt> class). You can override it with your own implementation or listen to the <tt>onSort</tt> event as described in the previous section.
| |
| − |
| |
| − | '''Tip''': Sorting a large amount of live data could degrade the performance significantly. It is better to intercept the onSort event or the sort method to handle it effectively. Please refer to the '''Sort Live Data''' section further down.
| |
| − |
| |
| − | === Special Properties ===
| |
| − | ==== The checkmark Property ====
| |
| − | The <tt>checkmark</tt> attribute controls whether to display a checkbox or a radio button in front of each list item.
| |
| − |
| |
| − | [[Image:10000000000001C20000005540C9B7A9.png]]
| |
| − |
| |
| − | In the following example, you will notice how a checkbox is added automatically when you move a list item from the left listbox to the right one. The checkbox is then removed when you move a list item from the right listbox to the left listbox.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <hbox>
| |
| − | <listbox id="src" rows="0" multiple="true" width="200px">
| |
| − | <listhead>
| |
| − | <listheader label="Population"/>
| |
| − | <listheader label="Percentage"/>
| |
| − | </listhead>
| |
| − | <listitem id="a" value="A">
| |
| − | <listcell label="A. Graduate"/>
| |
| − | <listcell label="20%"/>
| |
| − | </listitem>
| |
| − | <listitem id="b" value="B">
| |
| − | <listcell label="B. College"/>
| |
| − | <listcell label="23%"/>
| |
| − | </listitem>
| |
| − | <listitem id="c" value="C">
| |
| − | <listcell label="C. High School"/>
| |
| − | <listcell label="40%"/>
| |
| − | </listitem>
| |
| − | <listitem id="d" value="D">
| |
| − | <listcell label="D. Others"/>
| |
| − | <listcell label="17%"/>
| |
| − | </listitem>
| |
| − | </listbox>
| |
| − | <vbox>
| |
| − | <button label="=>" onClick="move(src, dst)"/>
| |
| − | <button label="<=" onClick="move(dst, src)"/>
| |
| − | </vbox>
| |
| − | <listbox id="dst" checkmark="true" rows="0" multiple="true" width="200px">
| |
| − | <listhead>
| |
| − | <listheader label="Population"/>
| |
| − | <listheader label="Percentage"/>
| |
| − | </listhead>
| |
| − | <listitem id="e" value="E">
| |
| − | <listcell label="E. Supermen"/>
| |
| − | <listcell label="21%"/>
| |
| − | </listitem>
| |
| − | </listbox>
| |
| − | <zscript>
| |
| − | void move(Listbox src, Listbox dst) {
| |
| − | Listitem s = src.getSelectedItem();
| |
| − | if (s == null)
| |
| − | Messagebox.show("Select an item first");
| |
| − | else
| |
| − | s.setParent(dst);
| |
| − | }
| |
| − | </zscript>
| |
| − | </hbox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | [[Image:10000000000000CD0000006D96B78742.png]]
| |
| − |
| |
| − | Note: If the <tt>multiple</tt> attribute is false, radio buttons are displayed instead, as demonstrated by the right hand listbox.
| |
| − |
| |
| − | ==== The vflex Property ====
| |
| − | The <tt>vflex</tt> property controls whether the listbox will grow or shrink vertically to fit the given space. It is named vertical flexibility. For example, if the list is too big to fit in the browser window, its』 height will decrease to make the whole list control visible in the browser window.
| |
| − |
| |
| − | This property is ignored if the <tt>rows</tt> attribute is specified.
| |
| − |
| |
| − | ==== The maxlength Property ====
| |
| − | The <tt>maxlength</tt> property defines the maximum number of characters visible at the browser. By setting this attribute, you are able to create a narrower list box.
| |
| − |
| |
| − | === Live Data ===
| |
| − | Like grids<ref name="ftn41">The concept is similar to Swing』s (<tt>javax.swing.ListModel</tt>).</ref>, list boxes support ''live data''. With live data, developers can separate data from the view. In other words, developers need only to provide the data by implementing the <tt>org.zkoss.zul.ListModel</tt> interface, rather than manipulating the list box directly.
| |
| − |
| |
| − |
| |
| − | The benefits are twofold:
| |
| − |
| |
| − | * It is easier to use different views to display the same set of data.
| |
| − | * The list box sends the data to the client only if it is visible. This saves a lot of network traffic if there is a large amount of data.
| |
| − |
| |
| − | There are three steps to make use of live data.
| |
| − |
| |
| − | 1 Prepare the data in the form of a <tt>ListModel</tt>. ZK has a concrete implementation called <tt>org.zkoss.zul.SimpleListModel</tt> for representing an array of objects.
| |
| − | 2 Implement the <tt>org.zkoss.zul.RowRenderer</tt> interface for rendering a row of data into the grid.
| |
| − |
| |
| − | ** This is optional. If it is not specified the default renderer is used to render the data into the first column.
| |
| − | ** You can implement different renderers for representing the same data in different views.
| |
| − |
| |
| − | 3 Set the data in the <tt>model</tt> attribute and, optionally, the renderer in the <tt>rowRenderer</tt> attribute.
| |
| − |
| |
| − | [[Image:1000000000000132000000E3AE1693E7.png]]
| |
| − |
| |
| − | In the following example, we prepared a list model called <tt>strset</tt>, assigned it to a list box through the <tt>model</tt> attribute. Then, the list box will do the rest.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <window title="Livedata Demo" border="normal">
| |
| − | <zscript>
| |
| − | String[] data = new String[30];
| |
| − | for(int j=0; j < data.length; ++j) {
| |
| − | data[j] = "option "+j;
| |
| − | }
| |
| − | ListModel strset = new SimpleListModel(data);
| |
| − | </zscript>
| |
| − | <listbox width="200px" rows="10" model="${strset}">
| |
| − | <listhead>
| |
| − | <listheader label="Load on demend"/>
| |
| − | </listhead>
| |
| − | </listbox>
| |
| − | </window>
| |
| − | </source>
| |
| − |
| |
| − | ==== Sorting with Live Data ====
| |
| − | If you allow users to sort a grid with live data, you have to implement the interface, <tt>org.zkoss.zul.ListModelExt</tt>, in addition to the <tt>org.zkoss.zul.ListModel</tt>.
| |
| − |
| |
| − | <source lang="java" >
| |
| − | class MyListModel implements ListModel, ListModelExt {
| |
| − | public void sort(Comparator cmpr, boolean ascending) {
| |
| − | //do the real sorting
| |
| − | //notify the listbox (or grid) that data is changed by use of ListDataEvent
| |
| − | }
| |
| − | }
| |
| − | </source>
| |
| − |
| |
| − | When a user wants to sort the listbox, the listbox will invoke the <tt>sort</tt> method of <tt>ListModelExt</tt> to sort the data. In other words, the sorting is done by the list model, rather than the listbox.
| |
| − |
| |
| − | After sorting, the list model will notify the listbox by invoking the <tt>onChange</tt> method of the listbox』s registered <tt>org.zkoss.zul.event.ListDataListener</tt> instances. These are registered by the <tt>addListDataListener</tt> method. In most cases, all the data is changed, so the list model usually sends the following event:
| |
| − |
| |
| − | <source lang="java" >
| |
| − | new ListDataEvent(this, ListDataEvent.CONTENTS_CHANGED, -1, -1)
| |
| − | </source>
| |
| − |
| |
| − | '''Note''': the implementation of the <tt>ListModel</tt> and <tt>ListModelExt</tt> is independent of the visual presentation. In other words, they can be used with grids, listboxes and any other components supporting <tt>ListModel</tt>.
| |
| − |
| |
| − | If you require maximum flexibility, you should not assume the component to used, instead use <tt>ListDataEvent</tt> to communicate.
| |
| − |
| |
| − | === List Boxes Contain Buttons ===
| |
| − | In theory, a list cell can contain any other components, as demonstrated below.
| |
| − |
| |
| − | [[Image:1000000000000101000000597E6A0365.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <listbox width="250px">
| |
| − | <listhead>
| |
| − | <listheader label="Population"/>
| |
| − | <listheader label="Percentage"/>
| |
| − | </listhead>
| |
| − | <listitem value="A">
| |
| − | <listcell><textbox value="A. Graduate"/></listcell>
| |
| − | <listcell label="20%"/>
| |
| − | </listitem>
| |
| − | <listitem value="B">
| |
| − | <listcell><checkbox label="B. College"/></listcell>
| |
| − | <listcell><button label="23%"/></listcell>
| |
| − | </listitem>
| |
| − | <listitem value="C">
| |
| − | <listcell label="C. High School"/>
| |
| − | <listcell><textbox cols="8" value="40%"/></listcell>
| |
| − | </listitem>
| |
| − | </listbox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | Notes:
| |
| − |
| |
| − | # Don't use a list box, when a grid is a better choice. The appearances of list boxes and grids are similar, but the listbox should only be used to represent a list of selectable items.
| |
| − | # Users are usually confused if a listbox contains editable components such as a <tt>textbox</tt> or a <tt>checkbox</tt>.
| |
| − | # Due to the limitation of the browsers, users cannot select a range of characters from text boxes.
| |
| − |
| |
| − | === Paging ===
| |
| − | A paging component is used to separate large amounts of content into multiple pages. For example, assume that you have 100 items and prefer to show 20 items at a time, you can use the paging components as follows.
| |
| − |
| |
| − | [[Image:100000000000007A00000013F689AD21.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <paging totalSize="100" pageSize="20"/>
| |
| − | </source>
| |
| − |
| |
| − | When a user clicks on the hyperlinks, the <tt>onPaging</tt> event is sent to the paging component along with an instance of <tt>org.zkoss.zul.event.PagingEvent</tt>. To decide which portion of your 100 items are visible, you should add a listener to the paging component.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <paging id="paging"/>
| |
| − | <zscript><![CDATA[
| |
| − | List result = new SearchEngine().find("ZK");
| |
| − | //assume SearchEngine.find() will return a list of items.
| |
| − | paging.setTotalSize(result.size());
| |
| − | paging.addEventListener("onPaging", new EventListener() {
| |
| − | public void onEvent(Event event) {
| |
| − | int pgno = event.getPaginal().getActivePage();
| |
| − | int ofs = pgno * event.getPaginal().getPageSize();
| |
| − | new Viewer().redraw(result, ofs, ofs + event.getPaginal().getPageSize() - 1);
| |
| − | //assume redraw(List result, int b, int e) will display
| |
| − | //from the b-th item to the e-th item
| |
| − | }
| |
| − | });
| |
| − | ]]>
| |
| − | </zscript>
| |
| − | </source>
| |
| − |
| |
| − | ==== Paging with List Boxes and Grids ====
| |
| − | The <tt>listbox</tt> and <tt>grid</tt> components support the paging intrinsically, so you don't need to specify a paging component explicitly as above unless you want to have different visual layout or to control multiple <tt>listbox</tt> and <tt>grid</tt>controls with one paging component.
| |
| − |
| |
| − | Please refer to the '''Grids''' section for more details.
| |
| − |
| |
| − | == See Also ==
| |
| − | From Other Chapter:
| |
| − | *[[Live_Data%2C_Paging%2C_setModel_and_Implement_your_own_renderer | Live Data, Paging, setModel and Implement your own renderer]]
| |
| − |
| |
| − | From smalltalk:
| |
| − | *[http://www.zkoss.org/smalltalks/loadondemand/ Use Load-On-Demand to Handle Huge Data]
| |
| − |
| |
| − | From ZK forum:
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6291%3BcategoryId%3D14%3B Retrieving selected items from a listBox]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6560%3BcategoryId%3D14%3B Add rows manually in Live Data grid ]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6208%3BcategoryId%3D14%3B Best practice and performance for menu tree | zul vs. java ]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6406%3BcategoryId%3D14%3B Refresh Listbox Model after button click ]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6204%3BcategoryId%3D14%3B How can i access a dinamyc field in a grid row]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D5782%3BcategoryId%3D14%3B listbox dependent on other listbox]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D5675%3BcategoryId%3D14%3B Scrollable Windows or Grids]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6032%3BcategoryId%3D14%3B Million Record Challenge]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D5869%3BcategoryId%3D14%3B Listbox not showing data?]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D5873%3BcategoryId%3D14%3B How to capture a grid cell select event?]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D5831%3BcategoryId%3D14%3B How to catch click events on Treeitem]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D5840%3BcategoryId%3D14%3B Listbox forgets checkbox selection]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D5727%3BcategoryId%3D14%3B Listbox problem]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D5751%3BcategoryId%3D14%3B Problem with Listbox selectedItem]
| |
| − |
| |
| − | === Notes ===
| |
| − |
| |
| − | <references />
| |
| | | | |
| | {{ ZKDevelopersGuidePageFooter}} | | {{ ZKDevelopersGuidePageFooter}} |
