Chosenbox"

From Documentation
(ZK-5182: Remove the allowScripts property)
 
(38 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
{{ZKComponentReferencePageHeader}}
 
{{ZKComponentReferencePageHeader}}
  
= Combobutton =
+
= Chosenbox =
*Demonstration:
+
*[https://www.zkoss.org/zkdemo/zk_pe_and_ee/combobox_chosenbox Demonstration]
 
*Java API: <javadoc>org.zkoss.zkmax.zul.Chosenbox</javadoc>
 
*Java API: <javadoc>org.zkoss.zkmax.zul.Chosenbox</javadoc>
*JavaScript API: <javadoc directory="jsdoc">zul.wgt.Combobutton</javadoc>
 
 
*JavaScript API: <javadoc directory="jsdoc">zkmax.inp.Chosenbox</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zkmax.inp.Chosenbox</javadoc>
 
*Style Guide: [[ZK_Style_Guide/XUL_Component_Specification/Chosenbox | Chosenbox]]
 
*Style Guide: [[ZK_Style_Guide/XUL_Component_Specification/Chosenbox | Chosenbox]]
Line 11: Line 10:
 
= Employment/Purpose =
 
= Employment/Purpose =
  
A component that similar to [[ZK_Component_Reference/Input/Combobox | Combobox]] but handle the multi-selection and the select order.
+
A component similar to [[ZK_Component_Reference/Input/Combobox | Combobox]] but handles the multi-selection and the select order.
  
 
= Example =
 
= Example =
==Normal ListModel==
 
  
In this way, all the content will send to client side and process at client side, this is pretty fast with few items but will cause performance issue at client side if there are lots of items (e.g., 40000 or more) in model and render/process them at once.
+
==Typical Usage==
  
[[Image:CompREF_Chosenbox_01.png]]
+
<ul>
 +
<li><b>creatable</b> attribute denotes whether or not to display <b>createMessage</b> when a user inputs a value that is non-existing in the model, and sends it back to the server along with an <b>onSearch</b> event when user clicks the ENTER key or separator.</li>
 +
 
 +
<li><b>emptyMessage</b> will be displayed as a placeholder if nothing is selected or focused.</li>
 +
 
 +
<li><b>noResultText</b> 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.</li>
 +
 
 +
<li><b>createMessage</b> 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.</li>
 +
 
 +
</ul>
 +
 
 +
When no item is selected or focused, <b>emptyMessage</b> is visible.
 +
 
 +
[[Image:CompREF_Chosenbox_msgEx_01.png]]
 +
 
 +
When there is no data to be shown in the model and data 0 already selected, <b>noResultText</b> appears.
 +
 
 +
[[Image:CompREF_Chosenbox_msgEx_02.png]]
 +
 
 +
When there is no item in the model but it is creatable, <b>createMessage</b> appears.
 +
 
 +
[[Image:CompREF_Chosenbox_msgEx_03.png]]
  
 
<source lang="xml">
 
<source lang="xml">
<zk>
+
    <zscript>
<zscript>
+
        ListModelList model = new ListModelList(Locale.getAvailableLocales());
import org.zkoss.zktest.test2.select.models.*;
+
    </zscript>
+
    <chosenbox width="400px"
ListModelList model = ListModelLists.
+
              model="${model}" creatable="true"
getModel(ListModelLists.MULTIPLE_AND_CLONEABLE);
+
              emptyMessage=" Please select some items."
</zscript>
+
              noResultsText=" No such item - {0} - and it is already in the model."
<chosenbox id="lbxThree" width="440px"
+
              createMessage=" No such item -{0} - but it is not in model either, you can try to create it.">
model="${model}" />
+
        <attribute name="onSearch">
</zk>
+
            Object obj = event.getValue();
 +
            ((ListModelList)model).add(obj);
 +
            self.addItemToSelection(obj);
 +
        </attribute>
 +
    </chosenbox>
 
</source>
 
</source>
  
==SubListModel==
 
  
In this way, the content of drop-down list will not rendered to client side, and is blank without input, server will provide the 'matched' content after user input some text. This will cause some delay at client side cause by the server processing time and network transfer time.
+
==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.  
  
See also: [http://books.zkoss.org/wiki/ZK_Component_Reference/Input/Combobox#Autocomplete_by_ListSubModel Combobox#Autocomplete_by_ListSubModel]
+
[[Image:CompREF_Chosenbox_01.png]]
  
 
<source lang="xml">
 
<source lang="xml">
<zk>
+
    <zscript>
<zscript>
+
        ListModelList model = new ListModelList(Locale.getAvailableLocales());
import org.zkoss.zktest.test2.select.models.*;
+
    </zscript>
+
    <chosenbox width="400px" model="${model}"/>
ListModelList model = ListModelLists.
 
getModel(ListModelLists.MULTIPLE_AND_CLONEABLE);
 
ListSubModel subModel = ListModels.toListSubModel(model);
 
</zscript>
 
<chosenbox id="lbxThree" width="440px"
 
model="${subModel}" />
 
</zk>
 
 
</source>
 
</source>
  
==creatable, emptyMessage, noResultsText and createMessage==
+
==Lazy Rendering==
  
The creatable attribute denotes whether display createMessage while user input a value which not in model, and send it back with onSearch event if user press the ENTER key or separator.
+
With <code>ListSubModel</code>, 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.
  
The emptyMessage will be displayed as a placeholder if nothing selected and not focused.
+
See also: [http://books.zkoss.org/wiki/ZK_Component_Reference/Input/Combobox#Autocomplete_by_ListSubModel Combobox#Autocomplete_by_ListSubModel]
  
The noResultText will be displayed if nothing match to the input value and can not create either, the syntax "{0}" will be replaced with the input value at client side.
+
<source lang="xml">
 +
    <zscript><![CDATA[
 +
        ListModelList model = new ListModelList(Locale.getAvailableLocales());
 +
        ListSubModel subModel = ListModels.toListSubModel(model);
 +
    ]]></zscript>
 +
    <chosenbox width="400px" model="${subModel}"/>
 +
</source>
  
The createMessage will be displayed in popup if nothing match to the input value but can create as new label, the syntax "{0}" will be replaced with the input value at client side.
 
  
<source lang="xml">
+
{{CustomItemRendering |chosenbox}}
<zk>
 
<zscript>
 
import org.zkoss.zktest.test2.select.models.*;
 
 
ListModelList model = ListModelLists.
 
getModel(ListModelLists.MULTIPLE_AND_CLONEABLE);
 
</zscript>
 
<chosenbox id="lbxThree" width="440px"
 
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>
 
</zk>
 
</source>
 
  
=Mouseless Entry Chosenbox=
+
=Keyboard Navigation Chosenbox=
  
* Press <tt>UP</tt> and <tt>DOWN</tt> to move the focus up and down by one option.
+
* Press <code>UP</code> and <code>DOWN</code> to move the focus up and down by one option.
* Press <tt>LEFT</tt> and <tt>RIGHT</tt> to move focus between selected item(s) and the input field.
+
* Press <code>LEFT</code> and <code>RIGHT</code> to move focus between selected item(s) and the input field.
* Press <tt>ESC</tt> to clear input and close drop-down list.
+
* Press <code>ESC</code> to clear input and close drop-down list.
* Press <tt>DELETE</tt> to delete the focused item and move focus to next item if any or input field.
+
* Press <code>DELETE</code> to delete the focused item and move focus to next item if any or input field.
* Press <tt>BACKSPACE</tt> to delete the focused item and move focus to previous item if any or input field.
+
* Press <code>BACKSPACE</code> to delete the focused item and move focus to previous item if any or input field.
* Press <tt>ENTER</tt> or <tt>specified separator</tt> to select the focused option.
+
* Press <code>ENTER</code> or <code>specified separator</code> to select the focused option.
  
 
=Properties=
 
=Properties=
* '''creatable''': specify whether send event to server when user input an inexist value then press ENTER or separator. Default: '''false'''
+
<ul>
* '''createMessage''': displayed in popup if nothing match to the input value and creatable is true, the syntax "{0}" will be replaced with the input value at client side.
+
<li>'''creatable''': specify whether to send an event to server when user inputs an non-existing value by clicking ENTER or separator. Default: '''false'''</li>
* '''disabled''': specify whether it is disabled. Default: '''false'''
+
<li>'''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</li>
* '''emptyMessage''': displayed as place holder in input if nothing selected and not focused.
+
<li>'''disabled''': specify whether or not it is disabled. Default: '''false'''</li>
* '''model''': specify the ListModel of this chosenbox. If you set ListModelList to it, All the content will send to client side and process at client side, this is pretty fast with few items but will cause performance issue at client side if there are lots of items (e.g., 40000 or more) in model. If you set ListSubMmodel to it, The content of drop-down list will not rendered to client side, and is blank without input, server will provide the 'matched' content after user input, this will cause some delay at client side cause by the server processing time and network transfer time.
+
<li>'''emptyMessage''': displayed as place holder in input if nothing is selected or focused</li>
* '''name''': specify the name of the input element of this component.
+
<li>'''model''': specify the <b>ListModel</b> of this <b>chosenbox</b></li>
* '''noResultsText''': displayed in popup if nothing match to the input value and creatable is false, the syntax "{0}" will be replaced with the input value at client side.
+
<ul>
* '''open''': specify whether open the drop-down list. Default: '''false'''
+
<li>If you set <b>ListModelList</b> to the model of <b>chosenbox</b>, 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</li>
* '''tabindex''': specify he tab order of the input node of this component.  Default: '''0'''
+
<li>If you set <b>ListSubModel</b> to the <b>chosenbox</b> 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</li>
* '''separator''': the separate chars will work as 'Enter' key, it will not considered as input value but send onSerch or onSelect while key up. Supports: 0-9, A-Z (case insensitive), and ,.;'[]/\-=.
+
</ul>
 +
<li>'''name''': specify the name of the input element of this component</li>
 +
<li>'''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</li>
 +
<li>'''open''': specify whether or not to open the drop-down list. Default: '''false'''</li>
 +
<li>'''tabindex''': specify the tab order of the input node of this component.  Default: '''0'''</li>
 +
<li>'''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 <code>,.;'[]/\-=</code></li>
 +
</ul>
  
 
=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>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>
  
Represents an event cause by user's the selection is changed at the client.
+
Represents an event caused by user's the selection changed at the client.
  
 
|-
 
|-
| <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>
  
Represents an event that indicates a the open state is changed at the client.
+
Represents an event that indicates an open state that is changed at the client.
 
|-
 
|-
| <center><tt>onSearch</tt></center>
+
| <center><code>onSearch</code></center>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.InputEvent</javadoc>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.InputEvent</javadoc>
  
Represents an event that indicates user input an inexist value then press ENTER or separator.
+
Represents an event that indicates users inputting an non-existing value by clicking ENTER or separator.
 
|-
 
|-
| <center><tt>onSearching</tt></center>
+
| <center><code>onSearching</code></center>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.InputEvent</javadoc>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.InputEvent</javadoc>
  
Represents an event caused by that user is input text.
+
Represents an event sent back to the server caused by user's input text.
 +
|-
 +
| <center><code>onItemClick</code></center>
 +
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.Event</javadoc>
 +
 
 +
Represents an event sent back to the server caused by clicking a selected tag.
 
|}
 
|}
  
Line 142: Line 155:
  
 
=Use Cases=
 
=Use Cases=
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Description !! Example Location
 
! Version !! Description !! Example Location
 
|-
 
|-
Line 152: Line 165:
 
=Version History=
 
=Version History=
 
{{LastUpdated}}
 
{{LastUpdated}}
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
Line 158: Line 171:
 
| April 3, 2012
 
| April 3, 2012
 
| Add the new Chosenbox component
 
| Add the new Chosenbox component
 +
|
 +
|-
 +
| 8.0.2
 +
| May 24, 2016
 +
| Add the new Event - onItemClick
 +
|
 
|}
 
|}
  
 
{{ZKComponentReferencePageFooter}}
 
{{ZKComponentReferencePageFooter}}

Latest revision as of 07:27, 23 February 2024

Chosenbox

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.

CompREF Chosenbox msgEx 01.png

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

CompREF Chosenbox msgEx 02.png

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

CompREF Chosenbox msgEx 03.png

    <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.

CompREF Chosenbox 01.png

    <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.

See also: Combobox#Autocomplete_by_ListSubModel

    <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

  • 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.

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 : 2024/02/23


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



Last Update : 2024/02/23

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