Introduction

Being able to let users to “select” is always a key feature in modern web applications. ZK framework has been providing various ways such as Selectbox, Combobox, Listbox to fulfill different selection needs. For complex selections, Tree Selections is available.

In ZK 9, we are glad to introduce a new component – Cascader. Cascader looks like a selectbox, but allows user to select options in a tree structure.

Demo

As we can see, we can drill-down and perform multi-layer selection. Note that only when the leaf item is selected, it is deemed as “selected” and the selection path would be updated and being displayed in the Cascader.

Here’s the ZUL file used in this demo:

ZUL

<zk>
<zscript><![CDATA[
   DefaultTreeModel model = new DefaultTreeModel(new DefaultTreeNode("ROOT",
      Arrays.asList(new DefaultTreeNode[] {
         new DefaultTreeNode("Taipei", Arrays.asList(new DefaultTreeNode[] {
            new DefaultTreeNode("Songshan Dist.", new ArrayList()),
            new DefaultTreeNode("Da'an Dist.", new ArrayList()),
            new DefaultTreeNode("Zhongshan Dist.",
              Arrays.asList(new DefaultTreeNode[] {
                new DefaultTreeNode("Potix Corp.", new ArrayList())
              }))
         })),
         new DefaultTreeNode("Taichung", new ArrayList()),
         new DefaultTreeNode("kaohsiung", new ArrayList())
      })));
]]></zscript>
   <separator />
   <cascader model="${model}" width="300px" />
</zk>

Cascader Component

We provide several API methods / events for this component:

  • setItemConverter(Converter<Collection<E>, String>)
    Sets the converter that generates the label text shown in the cascader from selected path. By default the label is generated by joining the items along the selected path separated by slashes, i.g. “A/B/C”.
  • setItemRenderer(ItemRenderer<E>)
    Sets the renderer which is used to render each item from TreeModel.
  • setModel(ListModel<E>)
    Sets the tree model associated with this cascader.
  • setOpen(boolean)
    Drops down or closes the cascader popup.
  • setPlaceholder(String)
    Sets the placeholder text that is displayed when the selected item is empty.
  • setSelectedItem(E)
    Deselects all the currently selected items and selects the given item.
  • onSelect
    Represents an event caused by the user that the the leaf item is selected or selection is cleared.
  • onOpen
    Denotes that the user has opened or closed a component.

Keyboard Support

We can easily use keyboard to navigate items in Cascader.

  • Press Up/Down key would open the popup when the cascader is focused.
  • Press Esc key would close the popup.
  • Press Up, Down, Page Up, Page Down, Home, or End key would navigate within the items.
  • Press Right, Left key would open/close item layers.
  • Press Enter to select an item.

This component will be available in ZK 9.0. You can already try them out using the 9.0 RC or freshly (nightly) builds.

I hope you find this component interesting. Please let us know how you like it!
For further information, please check out component reference.

Downloads

The runnable demo project is available on Github.

If you enjoyed this post, please consider leaving a comment or subscribing to the RSS feed to have future articles delivered to your feed reader.

Leave a Reply