Introduction
In ZK Framework, there are Selectbox, Combobox, Listbox and Chosenbox allowing users to make single or multiple selections. But only Listbox and Chosenbox accept multiple selection. Now we introduce a new component named Searchbox that supports both single and multiple selection.
Demo
ZUL
<zk>
<zscript>
ListModel model = new ListModelArray(new String[] {
"North America", "South America", "Europe",
"Asia", "Africa", "Oceania", "Antarctica"
});
</zscript>
<searchbox model="${model}" placeholder="An unknown place"
autoclose="true">
<template name="model">
<html><![CDATA[
<i class="z-icon-globe"></i> ${each}
]]></html>
</template>
</searchbox>
</zk>
Searchbox Component
We provide several API methods / events for this component:
- setAutoclose(boolean)
Sets whether to automatically close the list if a user selected any item.
- setItemConverter(Converter<Collection<E>, String>)
Sets the converter that generates the label text shown in the searchbox from selected items.
- setItemRenderer(ItemRenderer<E>)
Sets the renderer which is used to render each item if getModel() is not null.
- setModel(ListModel<E>)
Sets the list model associated with this searchbox.
- setMultiple(boolean)
Sets whether multiple selections are allowed.
- setOpen(boolean)
Drops down or closes the list of items.
- setPlaceholder(String)
Sets the placeholder text that is displayed when the selected item is empty.
- setSearchMessage(String)
Sets the placeholder message of the search text field.
- setSelectedItem(E)
Deselects all of the currently selected items and selects the given item.
- setSelectedItems(Collection<E>)
Selects the given items. Must be non-null values.
- onAfterRender
Notifies one that the model’s data has been rendered.
- onSelect
Represents an event caused by the user that the list selection is changed at the client.
- onOpen
Denotes that the user has opened or closed a component.
- onSearching
Notifies one that the user is searching by keywords.
Keyboard Support
Searchbox can be commanded by a keyboard.
- When getting focused, pressing Up/Down key opens the popup.
- Press Esc key closes the opened popup.
- Press Up, Down, Page Up, Page Down, Home, or End key to navigate within items.
- Press Enter to select/unselect an item.
- Selecting an item with Shift key pressed selects/unselects a range of items.
Model Template
You can customize the displayed label of an item by using a template. It supports <label> and <html>.
Since Searchbox doesn’t allow any child component, the content is always rendered label or Html.
ListSubModel support
A Searchbox allows ListModel as a data source. If a ListSubModel is provided, the items will be rendered on-demand. That means no item will be displayed at first and the user needs to type keywords to search for the resulting items. It is beneficial if the model contains lots of data.
ItemConverter
By implementing the Converter class, you can customize the label of a Searchbox.
myComp.setItemConverter(items ->
String.format("Selected %d item(s)", items.size())
);
The resulting label will look like “Selected n item(s)”.
The whole demo project can be found on the GitHub project and we welcome you to try it out and share with us your feedback.
The component will be available in ZK 9.0. You can already try them out using the 9.0 freshly (nightly) builds. Feel free to test them and tell us how you like it!
For further information check out component reference.
