Revision as of 04:02, 5 December 2023

Chosenbox

Demonstration
Java API: Chosenbox
JavaScript API: Chosenbox
Style Guide: Chosenbox
Available for ZK:

Employment/Purpose

A component similar to Combobox but handles the multi-selection and the select order.

Example

Typical Usage

creatable attribute denotes whether or not to display createMessage when a user inputs a value that is non-existing in the model, and sends it back to the server along with an onSearch event when user clicks the ENTER key or separator.
emptyMessage will be displayed as a placeholder if nothing is selected or focused.
noResultText will be displayed if nothing matches the input value and it cannot be created either; syntax "{0}" will be replaced with the input value at client side.
createMessage will be displayed in popup if nothing matches the input value but can be created as new label; syntax "{0}" will be replaced with the input value at the client-side.

When no item is selected or focused, emptyMessage is visible.

When there is no data to be shown in the model and data 0 already selected, noResultText appears.

When there is no item in the model but it is creatable, createMessage appears.

    <zscript>
        ListModelList model = new ListModelList(Locale.getAvailableLocales());
    </zscript>
    <chosenbox width="400px"
               model="${model}" creatable="true"
               emptyMessage=" Please select some items."
               noResultsText=" No such item - {0} - and it is already in the model."
               createMessage=" No such item -{0} - but it is not in model either, you can try to create it.">
        <attribute name="onSearch">
            Object obj = event.getValue();
            ((ListModelList)model).add(obj);
            self.addItemToSelection(obj);
        </attribute>
    </chosenbox>

Rendering All

Here, all the content will be sent to and processed at the client side. The rendering process is pretty fast with a few items but may cause performance issue when the model exceeds 40,000 items and rendering them all at once.

    <zscript>
        ListModelList model = new ListModelList(Locale.getAvailableLocales());
    </zscript>
    <chosenbox width="400px" model="${model}"/>

Lazy Rendering

With ListSubModel, Chosenbox doesn't render any DOM elements in the drop-down list at first. Until a user enters a character, it retrieves 'matched' items from the server-side and renders them in the drop-down list. This might produce some delay at the client side because of server processing time and network latency.

    <zscript><![CDATA[
        ListModelList model = new ListModelList(Locale.getAvailableLocales());
        ListSubModel subModel = ListModels.toListSubModel(model);
    ]]></zscript>
    <chosenbox width="400px" model="${subModel}"/>

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}:

   <chosenbox>
       <template name="model">[${each}]</template>
   </chosenbox>

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.

Keyboard Navigation Chosenbox

Press UP and DOWN to move the focus up and down by one option.
Press LEFT and RIGHT to move focus between selected item(s) and the input field.
Press ESC to clear input and close drop-down list.
Press DELETE to delete the focused item and move focus to next item if any or input field.
Press BACKSPACE to delete the focused item and move focus to previous item if any or input field.
Press ENTER or specified separator to select the focused option.

Properties

allowScripts: specify whether runnable scripts are allowed. Default: false with <script>...</script> and onXXX attributes removed from the output of the renderer by the engine specified by the org.zkoss.zkmax.zul.chosenbox.engine.class library property
creatable: specify whether to send an event to server when user inputs an non-existing value by clicking ENTER or separator. Default: false
createMessage: displayed in popup if nothing matches the input value and creatable is true; syntax "{0}" will be replaced with the input value at client side
disabled: specify whether or not it is disabled. Default: false
emptyMessage: displayed as place holder in input if nothing is selected or focused
model: specify the ListModel of this chosenbox

If you set ListModelList to the model of chosenbox, all the content will be sent to and processed at the client-side, The rendering process is pretty fast with a few items but may cause performance issue when the model exceeds 40,000 items and rendering them all at once
If you set ListSubModel to the chosenbox model, the content of the drop-down list will not be rendered to the client-side,and will remain blank until user enters an input. The server will then provide a 'matched' content for the input. This will cause some delay at the client side because of server processing time and network transfer time

name: specify the name of the input element of this component
noResultsText: displayed in popup window if nothing matches the input value and creatable is false; syntax "{0}" will be replaced with the input value at client-side
open: specify whether or not to open the drop-down list. Default: false
tabindex: specify the tab order of the input node of this component. Default: 0
separator: the separate characters will work as 'Enter' key when clicked on; it will not be considered as an input value. Upon releasing the key, it will an send onSearch or onSelect event depending on the situation. Supports: 0-9, A-Z (case insensitive), and ,.;'[]/\-=

Supported Events

Name	Event Type
`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.
`onSearch`	Event: InputEvent Represents an event that indicates users inputting an non-existing value by clicking ENTER or separator.
`onSearching`	Event: InputEvent Represents an event sent back to the server caused by user's input text.
`onItemClick`	Event: Event Represents an event sent back to the server caused by clicking a selected tag.

Inherited Supported Events: HtmlBasedComponent

Supported Molds

The default mold

Supported Children

None

Use Cases

Version	Description	Example Location
6.0.1+	Creatable Chosenbox	Chosenbox – A beautiful and powerful multiple combobox

Version History

Last Update : 2023/12/05

Version	Date	Content
6.0.1	April 3, 2012	Add the new Chosenbox component
8.0.2	May 24, 2016	Add the new Event - onItemClick
10.0.0	September 11, 2023	Add the new allowScripts property