Cascader"

From Documentation
m (correct javadoc package name)
 
(29 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
= Cascader =
 
= Cascader =
  
*Demonstration:
+
* [https://www.zkoss.org/zkdemo/combobox/cascader Demonstration]
 
*Java API: <javadoc>org.zkoss.zkmax.zul.Cascader</javadoc>
 
*Java API: <javadoc>org.zkoss.zkmax.zul.Cascader</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zkmax.inp.Cascader</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zkmax.inp.Cascader</javadoc>
 
{{ZK EE}}
 
{{ZK EE}}
[ since 9.0.0 ]
+
{{versionSince| 9.0.0}}
 +
<!-- https://tracker.zkoss.org/browse/ZK-4392 -->
  
 
= Employment/Purpose =
 
= Employment/Purpose =
A Cascader is a dropdown list in a tree structure, and it supports TreeModel.
+
Cascader is used to select an item from a hierarchical structure of data. It accepts a TreeModel.
  
 
= Example =
 
= Example =
  
[[File:Cascader-example.png]]
+
[[File:cascader-basic.png]]
  
 
<source lang="xml" >
 
<source lang="xml" >
 
     <zscript><![CDATA[
 
     <zscript><![CDATA[
        DefaultTreeModel tm = new DefaultTreeModel(new DefaultTreeNode("ROOT",
+
    DefaultTreeModel treeModel = new DefaultTreeModel(new DefaultTreeNode("ROOT",
        Arrays.asList(new DefaultTreeNode[]{
+
            Arrays.asList(new DefaultTreeNode[]{
                new DefaultTreeNode("David", Arrays.asList(new TreeNode[]{new DefaultTreeNode("David-1"),
+
                    new DefaultTreeNode("USA",
                                new DefaultTreeNode("David-2")})),
+
                            Arrays.asList(new TreeNode[]{new DefaultTreeNode("New York"),new DefaultTreeNode("Los Angelas")})),
                new DefaultTreeNode("Thomas",new ArrayList()),
+
                    new DefaultTreeNode("Japan",
                new DefaultTreeNode("Steven",new ArrayList())})));
+
                            Arrays.asList(new TreeNode[]{new DefaultTreeNode("Tokyo"),new DefaultTreeNode("Kyoto")})),
 +
                    new DefaultTreeNode("New Zealand",
 +
                            Arrays.asList(new TreeNode[]{new DefaultTreeNode("Auckland"),new DefaultTreeNode("Queenstown")}))}
 +
            )));
 
     ]]></zscript>
 
     ]]></zscript>
     <cascader width="300px" model="${tm}" />
+
     <cascader width="300px" model="${treeModel}"/>
 
</source>
 
</source>
  
Users can select in layers, and the selection path would be converted into text. (Default is joining by slashes, i.g. "A/B/C")
+
Users can select in layers, and the selected items are converted into text. (Default: joining by slashes, i.g. "A/B/C")
 +
 
 +
{{CustomItemRendering |cascader}}
  
 
= Properties =
 
= Properties =
Line 36: Line 42:
  
 
== ItemConverter ==
 
== ItemConverter ==
The converter generates the label text shown in the cascader. By implementing your own <javadoc>org.zkoss.util.Converter</javadoc>, you can generate the label that represents the selected item. The default implementation is joining all the <code>toString()</code> result of items by slashes.
+
Specify a full qualified class name that implements <javadoc>org.zkoss.util.Converter</javadoc>.
 +
The default implementation is joining all the <code>toString()</code> result of items by slashes <code>/</code>.
  
== ItemRenderer ==
+
By implementing your own one, you can generate a custom text that represents the selected item.
See also: [[ZK_Developer's_Reference/MVC/View/Renderer/Cascader_Renderer]]
 
  
The item renderer is used to render each item.
 
  
By implementing your own <javadoc>org.zkoss.zul.ItemRenderer</javadoc>, you can generate the HTML fragment for the data model. Normally you would like to use the default implementation and use <code>&lt;template name="model"&gt;</code> instead.
+
{{CustomItemRendering |cascader}}
  
 
== Model ==
 
== Model ==
Line 55: Line 60:
 
(Default: empty)
 
(Default: empty)
  
== selectedItem ==
+
== SelectedItem ==
 
Represents the selected item, or null if no item is selected.
 
Represents the selected item, or null if no item is selected.
  
A non-leaf item can't be selected in the cascader. For example, users can only select item C in an A - B - C structure. But items A and B can't be selected.
+
Items are selected only if the leaf item is selected. For example, in an A - B - C structure, selected item remains null until the leaf node C is selected.
  
 
=Supported Events=
 
=Supported Events=
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Event Type</center>
 
! <center>Event Type</center>
 
|-
 
|-
| <center><tt>onAfterRender</tt></center>
+
{{onAfterRender}}
| '''Event:'''  <javadoc>org.zkoss.zk.ui.event.Event</javadoc>
 
 
 
Notifies one that the model's data has been rendered.
 
 
|-
 
|-
| <center><tt>onSelect</tt></center>
+
| <center><code>onSelect</code></center>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.SelectEvent</javadoc>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.SelectEvent</javadoc>
  
Line 76: Line 78:
  
 
|-
 
|-
| <center><tt>onOpen</tt></center>
+
| <center><code>onOpen</code></center>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.OpenEvent</javadoc>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.OpenEvent</javadoc>
  
Line 89: Line 91:
 
  * None
 
  * None
  
= Use Cases =
 
 
{| border='1px' | width="100%"
 
! Version !! Description !! Example Location
 
|-
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
|}
 
 
= Version History =
 
  
{{LastUpdated}}
 
{| border='1px' | width="100%"
 
! Version !! Date !! Content
 
|-
 
| 9.0.0
 
| November, 2019
 
| [https://tracker.zkoss.org/browse/ZK-4392 ZK-4392]: Provide a cascader component
 
|}
 
  
 
{{ZKComponentReferencePageFooter}}
 
{{ZKComponentReferencePageFooter}}

Latest revision as of 02:48, 22 December 2023

Cascader

  • Available for ZK:
  • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ee.png

Since 9.0.0

Employment/Purpose

Cascader is used to select an item from a hierarchical structure of data. It accepts a TreeModel.

Example

Cascader-basic.png

    <zscript><![CDATA[
    DefaultTreeModel treeModel = new DefaultTreeModel(new DefaultTreeNode("ROOT",
            Arrays.asList(new DefaultTreeNode[]{
                    new DefaultTreeNode("USA",
                            Arrays.asList(new TreeNode[]{new DefaultTreeNode("New York"),new DefaultTreeNode("Los Angelas")})),
                    new DefaultTreeNode("Japan",
                            Arrays.asList(new TreeNode[]{new DefaultTreeNode("Tokyo"),new DefaultTreeNode("Kyoto")})),
                    new DefaultTreeNode("New Zealand",
                            Arrays.asList(new TreeNode[]{new DefaultTreeNode("Auckland"),new DefaultTreeNode("Queenstown")}))}
            )));
    ]]></zscript>
    <cascader width="300px" model="${treeModel}"/>

Users can select in layers, and the selected items are converted into text. (Default: joining by slashes, i.g. "A/B/C")

Custom Item Rendering

Since this component has no child component like Listbox, if you want to render its items differently, there 2 ways:

Change text

If you just want to change the text e.g. enclosing it with brackets, just put <template> as its child and add characters with ${each}:

   <cascader>
       <template name="model">[${each}]</template>
   </cascader>
  • The template only allows text that can be converted into a ZK Label.

Change HTML Structure

If you want to make more changes e.g. adding tooltips by setting title attributes, you need to create your own ItemRenderer. See ZK Developer's Reference/MVC/View/Renderer/Item Renderer.

Properties

Disabled

Sets whether it is disabled. A disabled component can't interact with users.

ItemConverter

Specify a full qualified class name that implements Converter. The default implementation is joining all the toString() result of items by slashes /.

By implementing your own one, you can generate a custom text that represents the selected item.


Custom Item Rendering

Since this component has no child component like Listbox, if you want to render its items differently, there 2 ways:

Change text

If you just want to change the text e.g. enclosing it with brackets, just put <template> as its child and add characters with ${each}:

   <cascader>
       <template name="model">[${each}]</template>
   </cascader>
  • The template only allows text that can be converted into a ZK Label.

Change HTML Structure

If you want to make more changes e.g. adding tooltips by setting title attributes, you need to create your own ItemRenderer. See ZK Developer's Reference/MVC/View/Renderer/Item Renderer.

Model

The tree model associated with this cascader.

Open

Drops down or closes the list of items.

Placeholder

When the selected item is empty, the placeholder text would be displayed. (Default: empty)

SelectedItem

Represents the selected item, or null if no item is selected.

Items are selected only if the leaf item is selected. For example, in an A - B - C structure, selected item remains null until the leaf node C is selected.

Supported Events

Name
Event Type
onAfterRender
Event: Event

Notifies one that the model's data has been rendered as components on the server side.

onSelect
Event: SelectEvent

Represents an event caused by user's the selection changed at the client.

onOpen
Event: OpenEvent

Represents an event that indicates an open state that is changed at the client.

Supported Children

* None




Last Update : 2023/12/22

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.