Searchbox"
(Searchbox init) |
m (correct javadoc package name) |
||
(16 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
{{ZKComponentReferencePageHeader}} | {{ZKComponentReferencePageHeader}} | ||
− | |||
− | |||
= Searchbox = | = Searchbox = | ||
− | + | *Demonstration: [https://github.com/zkoss-demo/zksearchbox-demo zkoss-demo/zksearchbox-demo] | |
− | *Demonstration: | + | *Java API: <javadoc>org.zkoss.zkmax.zul.Searchbox</javadoc> |
− | *Java API: <javadoc>org.zkoss | ||
*JavaScript API: <javadoc directory="jsdoc">zkmax.inp.Searchbox</javadoc> | *JavaScript API: <javadoc directory="jsdoc">zkmax.inp.Searchbox</javadoc> | ||
− | + | {{ZK EE}} | |
− | + | [ since 9.0.0 ] | |
= Employment/Purpose = | = Employment/Purpose = | ||
− | A | + | A dropdown list that allows users to search and select items. |
= Example = | = Example = | ||
+ | [[File:Searchbox-example.png]] | ||
<source lang="xml" > | <source lang="xml" > | ||
− | + | <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> | ||
</source> | </source> | ||
=Mouseless Entry Searchbox= | =Mouseless Entry Searchbox= | ||
− | * <tt>UP</tt> or <tt>DOWN</tt> to pop up the list. | + | * <tt>UP</tt> or <tt>DOWN</tt> to pop up the list if being focused. |
* <tt>ESC</tt> to close the list. | * <tt>ESC</tt> to close the list. | ||
− | * <tt>UP</tt>, <tt>DOWN</tt>, <tt>HOME</tt>, <tt>END</tt>, <tt>PAGE UP</tt> and <tt>PAGE DOWN</tt> to change the selection of the | + | * <tt>UP</tt>, <tt>DOWN</tt>, <tt>HOME</tt>, <tt>END</tt>, <tt>PAGE UP</tt> and <tt>PAGE DOWN</tt> to change the selection of the item from the list. |
* <tt>ENTER</tt> to confirm the change of selection. | * <tt>ENTER</tt> to confirm the change of selection. | ||
=Properties= | =Properties= | ||
− | == | + | ==Autoclose== |
− | == | + | |
− | == | + | Sets whether to automatically close the list if a user selected any item. The default value is <code>false</code>. It means even if the user selected an item, the list still remains open. You might want to set it as <code>true</code> in single selection mode (multiple=false). |
− | == | + | |
− | = | + | ==Disabled== |
− | ==multiple== | + | |
− | == | + | Sets whether it is disabled. A list can still be opened programmatically by calling <code>open()</code> even if the component is in the disabled state. |
− | == | + | |
− | == | + | ==ItemConverter== |
− | == | + | |
− | == | + | By implementing your own <javadoc>org.zkoss.util.Converter</javadoc>, you can generate the label that represents the selected items. The default implementation is joining all the <code>toString()</code> result of items by commas. |
+ | |||
+ | ==ItemRenderer== | ||
+ | |||
+ | See also: [[ZK_Developer's_Reference/MVC/View/Renderer/Searchbox_Renderer]] | ||
+ | |||
+ | 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><template name="model"></code> instead. | ||
+ | |||
+ | ==Model== | ||
+ | |||
+ | Since this component doesn't accept any child, you must specify a <code>ListModel</code>. | ||
+ | |||
+ | If a <javadoc>org.zkoss.zul.ListSubModel</javadoc> is provided, all the items will not be rendered to the client directly. Instead, users must type a keyword to search for a subset of the list. It's suitable for a large model. | ||
+ | |||
+ | <b>Note</b>: If you assign a ListModel to a searchbox, you should enable multiple selection with ListModel. Please do not set multiple on searchbox directly. You should set multiple on the model instead. | ||
+ | |||
+ | <source lang="xml" highlight="7"> | ||
+ | ... | ||
+ | List Items = new ArrayList(); | ||
+ | for (int i = 0; i < 1000; i++) { | ||
+ | Items.add("data "+i); | ||
+ | } | ||
+ | ListModelList model = new ListModelList(Items); | ||
+ | model.setMultiple(true); | ||
+ | ... | ||
+ | |||
+ | <searchbox model="${model}" ... /> | ||
+ | </source> | ||
+ | |||
+ | ==Multiple== | ||
+ | |||
+ | Sets whether multiple selections are allowed. | ||
+ | |||
+ | ==Open== | ||
+ | |||
+ | Drops down or closes the list of items. | ||
+ | |||
+ | ==Placeholder== | ||
+ | |||
+ | Sets the placeholder text that is displayed when there's nothing selected. | ||
+ | |||
+ | ==SearchMessage== | ||
− | + | Sets the placeholder message of the search text field. The default is "Type to search". | |
− | == | + | ==SelectedItem== |
− | + | Returns the selected item, or null if no item is selected. When multiple is true, it returns the first of the selected items. | |
+ | Don't use MVVM annotations in both <code>selectedItem</code> and <code>selectedItems</code> at the same time since <code>@save</code> <code>selectedItem</code> will deselect all of the currently selected items first. | ||
− | = | + | ==SelectedItems== |
+ | Returns all selected items. | ||
=Supported Events= | =Supported Events= | ||
Line 58: | Line 110: | ||
! <center>Event Type</center> | ! <center>Event Type</center> | ||
|- | |- | ||
− | | <center>onSelect</center> | + | | <center><tt>onAfterRender</tt></center> |
+ | | '''Event:''' <javadoc>org.zkoss.zk.ui.event.Event</javadoc> | ||
+ | |||
+ | Notifies one that the model's data has been rendered. | ||
+ | |- | ||
+ | | <center><tt>onSelect</tt></center> | ||
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.SelectEvent</javadoc> | | '''Event:''' <javadoc>org.zkoss.zk.ui.event.SelectEvent</javadoc> | ||
− | Represents an event caused by user | + | Represents an event caused by the user that the list selection is changed at the client. |
|- | |- | ||
| <center><tt>onOpen</tt></center> | | <center><tt>onOpen</tt></center> | ||
Line 74: | Line 131: | ||
Notifies one that the user is searching by keywords. | Notifies one that the user is searching by keywords. | ||
|} | |} | ||
− | + | *Inherited Supported Events: [[ZK_Component_Reference/Base_Components/HtmlBasedComponent#Supported_Events | HtmlBasedComponent]] | |
− | |||
− | |||
=Supported Children= | =Supported Children= | ||
− | none | + | * none |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=Version History= | =Version History= |
Revision as of 04:58, 18 November 2019
Searchbox
- Demonstration: zkoss-demo/zksearchbox-demo
- Java API: Searchbox
- JavaScript API: Searchbox
- Available for ZK:
[ since 9.0.0 ]
Employment/Purpose
A dropdown list that allows users to search and select items.
Example
<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>
Mouseless Entry Searchbox
- UP or DOWN to pop up the list if being focused.
- ESC to close the list.
- UP, DOWN, HOME, END, PAGE UP and PAGE DOWN to change the selection of the item from the list.
- ENTER to confirm the change of selection.
Properties
Autoclose
Sets whether to automatically close the list if a user selected any item. The default value is false
. It means even if the user selected an item, the list still remains open. You might want to set it as true
in single selection mode (multiple=false).
Disabled
Sets whether it is disabled. A list can still be opened programmatically by calling open()
even if the component is in the disabled state.
ItemConverter
By implementing your own Converter, you can generate the label that represents the selected items. The default implementation is joining all the toString()
result of items by commas.
ItemRenderer
See also: ZK_Developer's_Reference/MVC/View/Renderer/Searchbox_Renderer
By implementing your own ItemRenderer, you can generate the HTML fragment for the data model. Normally you would like to use the default implementation and use <template name="model">
instead.
Model
Since this component doesn't accept any child, you must specify a ListModel
.
If a ListSubModel is provided, all the items will not be rendered to the client directly. Instead, users must type a keyword to search for a subset of the list. It's suitable for a large model.
Note: If you assign a ListModel to a searchbox, you should enable multiple selection with ListModel. Please do not set multiple on searchbox directly. You should set multiple on the model instead.
...
List Items = new ArrayList();
for (int i = 0; i < 1000; i++) {
Items.add("data "+i);
}
ListModelList model = new ListModelList(Items);
model.setMultiple(true);
...
<searchbox model="${model}" ... />
Multiple
Sets whether multiple selections are allowed.
Open
Drops down or closes the list of items.
Placeholder
Sets the placeholder text that is displayed when there's nothing selected.
SearchMessage
Sets the placeholder message of the search text field. The default is "Type to search".
SelectedItem
Returns the selected item, or null if no item is selected. When multiple is true, it returns the first of the selected items.
Don't use MVVM annotations in both selectedItem
and selectedItems
at the same time since @save
selectedItem
will deselect all of the currently selected items first.
SelectedItems
Returns all selected items.
Supported Events
Event: Event
Notifies one that the model's data has been rendered. | |
Event: SelectEvent
Represents an event caused by the user that the list selection is changed at the client. | |
Event: OpenEvent
Denotes that the user has opened or closed a component. Note: unlike onClose, this event is only a notification. The client sends this event after opening or closing the component. | |
Event: Event
Notifies one that the user is searching by keywords. |
- Inherited Supported Events: HtmlBasedComponent
Supported Children
* none
Version History
Version | Date | Content |
---|---|---|
9.0.0 | September 2019 | ZK-4380: Provide a Searchbox component |