|
|
| Line 1: |
Line 1: |
| | {{ZKDevelopersGuidePageHeader}} | | {{ZKDevelopersGuidePageHeader}} |
| | | | |
| − | == Label ==
| |
| − | A label component represents a piece of text.
| |
| | | | |
| − | [[Image:FormAndInput_1.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <window border="normal">
| |
| − | Hello World
| |
| − | </window>
| |
| − | </source>
| |
| − |
| |
| − | If you want to add an attribute to a label, it has to be written as follows:
| |
| − |
| |
| − | [[Image:FormAndInput_2.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <window border="normal">
| |
| − | <label style="color: red" value="Hello World" />
| |
| − | </window>
| |
| − | </source>
| |
| − |
| |
| − | '''Tip''': ZUML is XML, not HTML, so it doesn't accept <tt><strong>&</strong>nbsp;</tt>. However, you can use <tt><strong>&</strong>#160;</tt> instead.
| |
| − |
| |
| − | === The pre, hyphen, maxlength and multiline Properties ===
| |
| − |
| |
| − | [since 5.0.0]
| |
| − |
| |
| − | You can control how a label is displayed using the <tt>pre</tt>, <tt>multiline</tt> and <tt>maxlength</tt> properties. For example, if you specify <tt>pre</tt> to be true, all white spaces, such as new lines, spaces and tabs, are preserved.
| |
| − |
| |
| − | {| border="1px"
| |
| − | ! <center>pre</center>
| |
| − | ! <center>multiline</center>
| |
| − | ! <center>maxlenth</center>
| |
| − | ! <center>Description</center>
| |
| − |
| |
| − | |-
| |
| − | | <center>true</center>
| |
| − | | <center>any</center>
| |
| − | | <center>any</center>
| |
| − | | All white spaces are preserved, including new lines, spaces and tabs.
| |
| − |
| |
| − | |-
| |
| − | | <center>false</center>
| |
| − | | <center>true</center>
| |
| − | | <center>any</center>
| |
| − | | New lines are preserved.
| |
| − |
| |
| − | |-
| |
| − | | <center>false</center>
| |
| − | | <center>false</center>
| |
| − | | <center>positive</center>
| |
| − | | The label only show its value up to the length of "maxlength".
| |
| − |
| |
| − | |-
| |
| − | | <center>false</center>
| |
| − | | <center>false</center>
| |
| − | | <center>0</center>
| |
| − | | The label is displayed regularly.
| |
| − |
| |
| − | |}
| |
| − |
| |
| − | [[Image:FormAndInput3_ZK5.PNG]]
| |
| − |
| |
| − | <source lang="xml">
| |
| − | <window border="normal" width="300px">
| |
| − | <vbox id="result">
| |
| − | <label id="lb1" pre="true" />
| |
| − | <label id="lb2" multiline="true" />
| |
| − | <label id="lb3" maxlength="10" />
| |
| − | <zscript><![CDATA[
| |
| − | lb1.value = "this thing has spaces.\nnext line.";
| |
| − | lb2.value = "this thing no space.\nnext line.";
| |
| − | lb3.value = "this is more than 10 chars.";
| |
| − | ]]></zscript>
| |
| − | </vbox>
| |
| − | </window>
| |
| − | </source>
| |
| − |
| |
| − | [For ZK3 users]
| |
| − |
| |
| − | This displaying rule is slightly different in ZK3.
| |
| − |
| |
| − | {| border="1px"
| |
| − | ! <center>hyphen</center>
| |
| − | ! <center>pre</center>
| |
| − | ! <center>maxlenth</center>
| |
| − | ! <center>Description</center>
| |
| − |
| |
| − | |-
| |
| − | | <center>false</center>
| |
| − | | <center>false</center>
| |
| − | | <center>positive</center>
| |
| − | | Truncated the characters that exceeds the specified <tt>maxlength</tt>.
| |
| − |
| |
| − | |-
| |
| − | | <center>true</center>
| |
| − | | <center>any</center>
| |
| − | | <center>positive</center>
| |
| − | | If the length of a line exceeds <tt>maxlength</tt>, the line is hyphenated.
| |
| − |
| |
| − | |-
| |
| − | | <center>false</center>
| |
| − | | <center>true</center>
| |
| − | | <center>any</center>
| |
| − | | <tt>maxlength</tt> is ignored.
| |
| − |
| |
| − | |-
| |
| − | | <center>any</center>
| |
| − | | <center>any</center>
| |
| − | | <center>0</center>
| |
| − | | <tt>hyphen</tt> is ignored.
| |
| − |
| |
| − | |}
| |
| − |
| |
| − | [[Image:FormAndInput_3.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <window border="normal" width="100px">
| |
| − | <vbox id="result">
| |
| − | </vbox>
| |
| − | <zscript><![CDATA[
| |
| − | String[] s = {"this is 9", "this is ten more to show",
| |
| − | "this framework", "performance is everything"};
| |
| − | for (int j = 0; j < s.length; ++j) {
| |
| − | Label l = new Label(s[j]);
| |
| − | l.maxlength = 9;
| |
| − | l.hyphen = true;
| |
| − | l.parent = result;
| |
| − | }
| |
| − | ]]>
| |
| − | </zscript>
| |
| − | </window>
| |
| − | </source>
| |
| − |
| |
| − | The <tt>multiline</tt> property is similar to the <tt>pre</tt> property, except it only preserves new lines and white space at the beginning of each line.
| |
| − |
| |
| − | == Buttons ==
| |
| − | There are two types of buttons: <tt>button</tt> and <tt>toolbarbutton</tt>. While the looks of the buttons are different, their behaviors are the same. The <tt>button</tt> component uses the HTML BUTTON tag, while the <tt>toolbarbutton</tt> component uses the HTML Anchor(A) tag.
| |
| − |
| |
| − | You could assign a label and an image to a button by utilizing the <tt>label</tt> and <tt>image</tt> attributes. If both are specified, the <tt>dir</tt> property controls which is displayed first, and the <tt>orient</tt> property controls whether the layout is horizontal or vertical.
| |
| − |
| |
| − | [[Image:FormAndInput_4.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <button label="Left" image="/img/folder.gif" width="125px"/>
| |
| − | <button label="Right" image="/img/folder.gif" dir="reverse" width="125px"/>
| |
| − | <button label="Above" image="/img/folder.gif" orient="vertical" width="125px"/>
| |
| − | <button label="Below" image="/img/folder.gif" orient="vertical" dir="reverse" width="125px"/>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | In addition to employing URLs to specify images, you can dynamically assign a generated image to a button using the <tt>setImageContent</tt> method. Refer to the following section for details.
| |
| − |
| |
| − | '''Tip:''' The <tt>setImageContent</tt> method is supplied by all components that have an <tt>image</tt> property. Simply put, <tt>setImageContent</tt> is used for dynamically generated images, while <tt>image</tt> is used for images identifiable by a URL.
| |
| − |
| |
| − | === The onClick Event and href Property ===
| |
| − | There are two ways to add behavior to a <tt>button</tt> and <tt>toolbarbutton</tt>. Firstly, you can specify a listener for the <tt>onClick</tt> event. Secondly, you could specify a URL for the <tt>href</tt> property. If both are specified, the <tt>href</tt> property has the higher priority, i.e., the onClick event won't be sent.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <window title="example">
| |
| − | <zscript>
| |
| − | void do_something_in_Java()
| |
| − | {
| |
| − | alert("hello");
| |
| − | //redirect to another page
| |
| − | }
| |
| − | </zscript>
| |
| − |
| |
| − | <button label="click me" onClick="do_something_in_Java()"/>
| |
| − | <button label="don't click that one, click me" href="/another_page.zul"/>
| |
| − | </window>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | === The sendRedirect Method of the org.zkoss.zk.ui.Execution Interface ===
| |
| − | When processing an event, you can decide to stop processing the current desktop and redirect to another page by using the <tt>sendRedirect</tt> method. In other words, from the user』s viewpoint the following two buttons have exactly the same effect.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <window>
| |
| − | <zscript>
| |
| − | void sendRedirect(url)
| |
| − | {
| |
| − | alert("sending redirect");
| |
| − | //send redirect url
| |
| − | }
| |
| − | </zscript>
| |
| − |
| |
| − | <button label="redirect" onClick="sendRedirect("another.zul")"/>
| |
| − | <button label="href" href="another.zul"/>
| |
| − | </window>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | Since the onClick event is sent to the server for processing, you are able to perform additional tasks before invoking <tt>sendRedirect</tt>, such as redirecting to another page only if certain conditions are satisfied.
| |
| − |
| |
| − | On the other hand, the <tt>href</tt> property is processed at the client side. Your application won't be notified when users click the button.
| |
| − |
| |
| − | ===Button supports OS mold===
| |
| − |
| |
| − | For those who prefer native Button styling, please use the OS mold as demonstrated below:
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <button mold="os" label="os mold"/>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − |
| |
| − | The difference lies in the generated HTM, OS molds will generate the <button> tag instead of <table> tags.
| |
| − |
| |
| − | == Radio and Radio Group ==
| |
| − | A radio button is a component that can be turned on and off. Radio buttons are grouped together using <tt>radiogroup</tt>. Only one radio button in a group may be selected at a time.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <radiogroup onCheck="alert(self.selectedItem.label)">
| |
| − | <radio label="Apple"/>
| |
| − | <radio label="Orange"/>
| |
| − | <radio label="Banana"/>
| |
| − | </radiogroup>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | === Versatile Layouts ===
| |
| − | You can add additional controls into <tt>radiogroups</tt> to achieve the desired layout, as illustrated below.
| |
| − |
| |
| − | [[Image:FormAndInput_5.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <radiogroup>
| |
| − | <grid>
| |
| − | <rows>
| |
| − | <row><radio label="Apple" selected="true"/> Fruit, music or computer</row>
| |
| − | <row><radio label="Orange"/><textbox/></row>
| |
| − | <row><radio label="Banana"/><datebox/></row>
| |
| − | </rows>
| |
| − | </grid>
| |
| − | </radiogroup>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | The radio button belongs to the nearest <tt>radiogroup</tt> ancestor. You can even nest one radio group within another and each of them will operate independently. However, there might be some sort of visual overlap.
| |
| − |
| |
| − | [[Image:FormAndInput_6.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <radiogroup>
| |
| − | <grid>
| |
| − | <rows>
| |
| − | <row>
| |
| − | <radio label="Apple" selected="true"/>
| |
| − | Fruit, music or computer
| |
| − | </row>
| |
| − | <row>
| |
| − | <radio label="Orange"/>
| |
| − |
| |
| − | <radiogroup>
| |
| − | <radio label="Small"/>
| |
| − | <radio label="Large" selected="true"/>
| |
| − | </radiogroup>
| |
| − | </row>
| |
| − | <row>
| |
| − | <radio label="Banana"/><datebox/>
| |
| − | </row>
| |
| − | </rows>
| |
| − | </grid>
| |
| − | </radiogroup>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | == Comboboxes ==
| |
| − | Components: <tt>combobox</tt> and <tt>comboitem</tt>.
| |
| − |
| |
| − | A combobox is a special text box which embeds a drop-down list. Using comboboxes, users are allowed to select items from a drop-down list, in addition to entering text manually.
| |
| − |
| |
| − | [[Image:FormAndInput_7.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <combobox>
| |
| − | <comboitem label="Simple and Rich"/>
| |
| − | <comboitem label="Cool!"/>
| |
| − | <comboitem label="Ajax and RIA"/>
| |
| − | </combobox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | '''Mouseless Entry<tt>combobox'''</tt>
| |
| − |
| |
| − | * <tt>Alt+DOWN</tt> to pop up the list.
| |
| − | * <tt>Alt+UP</tt> or <tt>ESC</tt> to close the list.
| |
| − | * <tt>UP</tt> and <tt>DOWN</tt> to change the selection of the items from the list.
| |
| − |
| |
| − | === The autodrop Property ===
| |
| − |
| |
| − | [[Image:FormAndInput_8.png]]
| |
| − |
| |
| − | By default, the drop-down list won't be opened until user clicks the button, or presses <tt>Alt+DOWN</tt>. However, you could set the <tt>autodrop</tt> property to true, meaning as soon as the user types a character the drop-down list will be opened. This is helpful for novice users, but it might be annoying for experienced users.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <combobox autodrop="true"/>
| |
| − | </source>
| |
| − |
| |
| − | === The description Property ===
| |
| − | You are able add a description to each combo item to make it more descriptive or assign an image to every item.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <combobox>
| |
| − | <comboitem label="Simple and Rich" image="/img/coffee.gif"
| |
| − | description="The simplest way to make Web applications rich"/>
| |
| − | <comboitem label="Cool!" image="/img/corner.gif"
| |
| − | description="The coolest technology"/>
| |
| − | <comboitem label="Ajax and RIA" image="/img/cubfirs.gif"
| |
| − | description="Rich Internet Application by Ajax"/>
| |
| − | </combobox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | [[Image:FormAndInput_9.png]]
| |
| − |
| |
| − | Akin to other components that support images, you are able to use the <tt>setImageContent</tt> method to assign a dynamically generated image to the <tt>comboitem</tt> component. Please refer to the '''Image''' section for details.
| |
| − |
| |
| − | === The onOpen Event ===
| |
| − | The <tt>onOpen</tt> event is sent to the application when a user opens the drop-down list. To defer the creation of combo items, you can use the <tt>fulfill</tt> attribute as shown below.
| |
| − |
| |
| − | [[Image:FormAndInput_10.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <combobox fulfill="onOpen">
| |
| − | <comboitem label="Simple and Rich"/>
| |
| − | <comboitem label="Cool!"/>
| |
| − | <comboitem label="Ajax and RIA"/>
| |
| − | </combobox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | Alternatively, you can listen to the <tt>onOpen</tt> event and prepare the drop-down list or change it dynamically as demonstrated below.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <zscript>
| |
| − | void prepare()
| |
| − | {
| |
| − | if (combo.getItemCount() == 0)
| |
| − | {
| |
| − | combo.appendItem("Simple and Rich");
| |
| − | combo.appendItem("Cool!");
| |
| − | combo.appendItem("Ajax and RIA");
| |
| − | }
| |
| − | }
| |
| − | </zscript>
| |
| − | <combobox id="combo" onOpen="prepare()" />
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | The <tt>appendItem</tt> method is equivalent to creating a combo item and then setting the combobox as its parent.
| |
| − |
| |
| − | === The onChanging Event ===
| |
| − | Since a combobox is also a text box, you are also able to listen to an <tt>onChanging</tt> event. By listening to this event, you can manipulate the drop-down list as demonstrated by Google Suggests<ref name="ftn42">http://www.google.com/webhp?complete=1&hl=en</ref>. This feature is sometimes called auto-complete.
| |
| − |
| |
| − | As illustrated below, you can populate the drop-down list based on what user is entering.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <zscript>
| |
| − | void suggest()
| |
| − | {
| |
| − | combo.getItems().clear();
| |
| − | if (event.value.startsWith("A")) {
| |
| − | combo.appendItem("Ace");
| |
| − | combo.appendItem("Ajax");
| |
| − | combo.appendItem("Apple");
| |
| − | } else if (event.value.startsWith("B")) {
| |
| − | combo.appendItem("Best");
| |
| − | combo.appendItem("Blog");
| |
| − | }
| |
| − | }
| |
| − | </zscript>
| |
| − |
| |
| − | <combobox id="combo" autodrop="true" onChanging="suggest()"/>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | Notice that, when the <tt>onChanging</tt> event is received, the content of the combobox has not changed. Therefore, you cannot use the <tt>value</tt> property of the combobox. Instead, you should use the <tt>value</tt> property of the event (<tt>org.zkoss.zk.ui.event.InputEvent</tt>).
| |
| − |
| |
| − | == Bandboxes ==
| |
| − |
| |
| − | [[Image:FormAndInput_11.png]]
| |
| − |
| |
| − | Components: <tt>bandbox</tt> and <tt>bandpopup</tt>.
| |
| − |
| |
| − | A bandbox is a special text box that embeds a customizable popup window (AKA a dropdown window). Like comboboxes, a bandbox consists of an input box and a popup window. The popup window is opened automatically, when a user click the button or presses the keys <tt>Alt+DOWN</tt>.
| |
| − |
| |
| − | Unlike comboboxes, the popup window of a bandbox can contain anything as it is designed to give developers maximum flexibility. A typical use is to provide a search dialog.
| |
| − |
| |
| − | [[Image:FormAndInput_12.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <bandbox id="bd">
| |
| − | <bandpopup>
| |
| − | <vbox>
| |
| − | <hbox>
| |
| − | Search
| |
| − | <textbox />
| |
| − | </hbox>
| |
| − | <listbox width="200px"
| |
| − | onSelect="bd.value=self.selectedItem.label; bd.closeDropdown();">
| |
| − | <listhead>
| |
| − | <listheader label="Name" />
| |
| − | <listheader label="Description" />
| |
| − | </listhead>
| |
| − | <listitem>
| |
| − | <listcell label="John" />
| |
| − | <listcell label="CEO" />
| |
| − | </listitem>
| |
| − | <listitem>
| |
| − | <listcell label="Joe" />
| |
| − | <listcell label="Engineer" />
| |
| − | </listitem>
| |
| − | <listitem>
| |
| − | <listcell label="Mary" />
| |
| − | <listcell label="Supervisor" />
| |
| − | </listitem>
| |
| − | </listbox>
| |
| − | </vbox>
| |
| − | </bandpopup>
| |
| − | </bandbox>
| |
| − | </source>
| |
| − |
| |
| − | '''Mouseless Entry<tt>bandbox'''</tt>
| |
| − |
| |
| − | * <tt>Alt+DOWN</tt> to pop up the list.
| |
| − | * <tt>Alt+UP</tt> or <tt>ESC</tt> to close the list.
| |
| − | * <tt>UP</tt> and <tt>DOWN</tt> to change the selection of the items from the list.
| |
| − |
| |
| − | === The closeDropdown Method ===
| |
| − | A popup window could contain any components, so it is the developer’s job to close the popup and copy any needed value from it.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <listbox width="200px"
| |
| − | onSelect="bd.value=self.selectedItem.label; bd.closeDropdown();">
| |
| − | </source>
| |
| − |
| |
| − | In the above example, we copy the selected item's label to the bandbox, and then close the popup.
| |
| − |
| |
| − | === The autodrop Property ===
| |
| − | [[Image:FormAndInput_13.png]]
| |
| − |
| |
| − | By default, the popup window won't be opened until user clicks the button, or presses <tt>Alt+DOWN</tt> on the keyboard. However, you can set the <tt>autodrop</tt> property to true and as soon as the user types a character the popup will be opened. This is helpful for novice users, but it might be annoying for experienced users.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <bandbox id="bd" autodrop="true">
| |
| − | <bandpopup>
| |
| − | ...
| |
| − | </bandpopup>
| |
| − | </bandbox>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | === The onOpen Event ===
| |
| − | If the user opens the popup window the <tt>onOpen</tt> event is sent to the application. By using the <tt>fulfill</tt> attribute with the <tt>onOpen</tt> value as shown below, you can defer the creation of the popup window.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <bandbox id="test">
| |
| − | <bandpopup fulfill="test.onOpen">
| |
| − | ...
| |
| − | </bandpopup>
| |
| − | </bandbox>
| |
| − | </source>
| |
| − |
| |
| − | Alternatively, you can prepare the popup window in Java by listening to the <tt>onOpen</tt> event, as depicted below.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <bandbox id="band" onOpen="prepare()"/>
| |
| − |
| |
| − | <zscript>
| |
| − | void prepare()
| |
| − | {
| |
| − | if (band.getPopup() == null) {
| |
| − | //create child elements
| |
| − | }
| |
| − | }
| |
| − | </zscript>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | === The onChanging Event ===
| |
| − | Since a bandbox is also a text box, you are also able to listen to an <tt>onChanging</tt> event. By listening to this event, you can manipulate the popup window in any fashion.
| |
| − | The code below illustrates capturing the user key and displaying information accordingly.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <zk>
| |
| − | <bandbox id="band" autodrop="true" onChanging="suggest()"/>
| |
| − | <zscript>
| |
| − | void suggest()
| |
| − | {
| |
| − | if (event.value.startsWith("A")) {
| |
| − | //do something
| |
| − | } else if (event.value.startsWith("B")) {
| |
| − | //do another
| |
| − | }
| |
| − | }
| |
| − | </zscript>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − |
| |
| − | Notice that, when the <tt>onChanging</tt> event is received, the content of the bandbox has not changed. Therefore, you cannot use the <tt>value</tt> property of the bandbox. Instead, you should use the <tt>value</tt> property of the event (<tt>org.zkoss.zk.ui.event.InputEvent</tt>).
| |
| − |
| |
| − | == Input Controls ==
| |
| − |
| |
| − | The following input controls are supported in the XUL component set: <tt>[[Developer_reference_The_XUL_Components_Components_Textbox|textbox]],</tt> <tt>[[Developer_reference_The_XUL_Components_Components_Intbox|intbox]],</tt> <tt>[[Developer_reference_The_XUL_Components_Components_Decimalbox|decimalbox]],</tt>
| |
| − | <tt>[[Developer_reference_The_XUL_Components_Components_Doublebox|doublebox]]</tt>, <tt>[[Developer_reference_The_XUL_Components_Components_Datebox|datebox]]</tt>,
| |
| − | <tt>[[Developer_reference_The_XUL_Components_Components_Timebox|timebox]]</tt>,
| |
| − | <tt>[[Developer_reference_The_XUL_Components_Components_Spinner|spinner]]</tt>,
| |
| − | <tt>[[Developer_reference_The_XUL_Components_Components_Combobox|combobox]]</tt>, and <tt>[[Developer_reference_The_XUL_Components_Components_Bandbox|bandbox]]</tt>. These controls allow users to input different types of data.
| |
| − | <source lang="xml" >
| |
| − | <grid fixedLayout="true">
| |
| − | <columns>
| |
| − | <column label="Type" width="150px" />
| |
| − | <column label="Content" />
| |
| − | </columns>
| |
| − | <rows>
| |
| − | <row>
| |
| − | <label value="UserName" width="150px" />
| |
| − | <textbox value="Jerry" width="150px" />
| |
| − | </row>
| |
| − | <row>
| |
| − | Password
| |
| − | <textbox type="password" value="123456789" width="150px" />
| |
| − | </row>
| |
| − | <row>
| |
| − | Re-type Password
| |
| − | <textbox type="password" value="123456789" width="150px" />
| |
| − | </row>
| |
| − | <row>
| |
| − | Age:
| |
| − | <intbox value="19" constraint="no negative,no zero"
| |
| − | width="150px" />
| |
| − | </row>
| |
| − | <row>
| |
| − | Phone:
| |
| − | <intbox constraint="no negative,no zero" width="150px"
| |
| − | value="12345678" />
| |
| − | </row>
| |
| − | <row>
| |
| − | Weight:
| |
| − | <decimalbox format="###.##" value="154.32" width="150px" />
| |
| − | </row>
| |
| − | <row>
| |
| − | Birthday:
| |
| − | <hbox>
| |
| − | <datebox id="db" width="150px" />
| |
| − | </hbox>
| |
| − | </row>
| |
| − | <row>
| |
| − | Address
| |
| − | <vbox>
| |
| − | <textbox width="250px"
| |
| − | value="123 W. 45 Street, New York, NY 10001" />
| |
| − | <hbox>
| |
| − | <label value="Zip code :" />
| |
| − | <intbox constraint="no negative,no zero"
| |
| − | width="150px" />
| |
| − | </hbox>
| |
| − | </vbox>
| |
| − | </row>
| |
| − | <row>
| |
| − | E-mail:
| |
| − | <textbox width="150px" value="zk@zkoss.org"
| |
| − | constraint="/.+@.+\.[a-z]+/: Please enter an e-mail address" />
| |
| − | </row>
| |
| − | <row>
| |
| − | Introduction:
| |
| − | <hbox>
| |
| − | <textbox id="intro" rows="3" width="250px">
| |
| − | <attribute name="value">I think ZK is the best! </attribute>
| |
| − | </textbox>
| |
| − | <vbox>
| |
| − | More line :
| |
| − | <spinner value="3" constraint="no negative,no zero" />
| |
| − | </vbox>
| |
| − | </hbox>
| |
| − | </row>
| |
| − | </rows>
| |
| − | </grid>
| |
| − |
| |
| − | </source>
| |
| − |
| |
| − | '''Tip:''' The combobox and bandbox are special input boxes and share common properties. These unique features will be discussed later in the '''Combobox''' and '''Bandbox''' sections.
| |
| − |
| |
| − | === The type Property ===
| |
| − | The <tt>type</tt> attribute can be used with the <tt>textbox</tt> based components and can be given the value <tt>password</tt>. By setting the type as password the text that is entered into the box cannot be viewed and is replaced by stars.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | Username: <textbox/>
| |
| − | Password: <textbox type="password"/>
| |
| − | </source>
| |
| − |
| |
| − | === The format Property ===
| |
| − | You are able to format the field by providing specifying the attribute with a formatting string. The default value is <tt>null</tt>. When the formatting of the <tt>datebox</tt> is null, it means the date will be outputted using the format <tt>yyyy/MM/dd</tt>. With regard to the <tt>intbox</tt> and <tt>decimalbox</tt>, it means no formatting will be applied.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <datebox format="MM/dd/yyyy"/>
| |
| − | <decimalbox format="#,##0.##"/>
| |
| − | </source>
| |
| − |
| |
| − | Like any other properties, you are able change the format dynamically, as depicted below.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <datebox id="db"/>
| |
| − | <button label="set MM-dd-yyyy" onClick="db.setFormat("MM-dd-yyyy")"/>
| |
| − | </source>
| |
| − |
| |
| − | '''Mouseless Entry <tt>datebox'''</tt>
| |
| − |
| |
| − | * <tt>Alt+DOWN</tt> to show the calendar
| |
| − | * <tt>LEFT, RIGHT, UP</tt> and <tt>DOWN</tt> to change the selected day on the calendar
| |
| − | * <tt>ENTER</tt> to activate the selection by copying the selected day to the <tt>datebox</tt> control
| |
| − | * <tt>Alt+UP</tt> or <tt>ESC</tt> to give up the selection and close the calendar
| |
| − |
| |
| − | === Constraints ===
| |
| − | You could specify what value to accept for input controls by use of the <tt>constraint </tt>property. It could be a combination of <tt>no positive</tt>, <tt>no negative</tt>, <tt>no zero</tt>, <tt>no empty</tt>, <tt>no future</tt>, <tt>no past</tt>, <tt>no today</tt>, and/or a regular expression. The first three constraints are applicable only to the <tt>intbox</tt> and <tt>decimalbox</tt>. The constraints of <tt>no future</tt>, <tt>no past</tt>, and <tt>no today</tt> are only applicable to the <tt>datebox</tt>. The constraint of <tt>no empty</tt> is applicable to any type of component. A regular expressions constraint is only applicable to String-type input components, such as the <tt>textbox</tt>., <tt>combobox</tt> and <tt>bandbox</tt>.
| |
| − |
| |
| − | To specify two or more constraints, use comma to separate them as follows.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <intbox constraint="no negative,no zero"/>
| |
| − | </source>
| |
| − |
| |
| − | To specify a regular expression, you may have to use the character <tt>/</tt> to enclose the regular expression as follows.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <textbox constraint="/.+@.+\.[a-z]+/"/>
| |
| − | </source>
| |
| − |
| |
| − | Notes:
| |
| − |
| |
| − | * The above statement is XML, so do ''not'' use <tt>\\</tt> to specify a backslash. However typing <tt>\\</tt> is necessary, if writing in Java.
| |
| − |
| |
| − | <source lang="java" >
| |
| − | new Textbox().setConstraint("/.+@.+\\.[a-z]+/");
| |
| − | </source>
| |
| − |
| |
| − | * You are allowed to mix regular expressions with other constraints by separating them with a comma.
| |
| − |
| |
| − | If you prefer to display different message to the default one, you can append the error message to the constraint with a colon.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <textbox constraint="/.+@.+\.[a-z]+/: e-mail address only"/>
| |
| − | <datebox constraint="no empty, no future: now or never"/>
| |
| − | </source>
| |
| − |
| |
| − | Notes:
| |
| − |
| |
| − | * The error message, if specified, must be the last element and start with colon.
| |
| − | * To support multiple languages, you could use the 「l」 function as depicted in the '''Internationalization''' chapter.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <textbox constraint="/.+@.+\.[a-z]+/: ${c:l('err.email.required')}"/>
| |
| − | </source>
| |
| − |
| |
| − | === Constraints for Datebox ===
| |
| − | In addition to the constraints described in the above section (such as <tt>no future</tt> and regular expressions), the <tt>datebox</tt> supports a wide range of dates. For example,
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <datebox constraint="between 20071225 and 20071203"/>
| |
| − | <datebox constraint="before 20071225"/>
| |
| − | <datebox constraint="after 20071225"/>
| |
| − | </source>
| |
| − |
| |
| − | Notices
| |
| − |
| |
| − | # The format of the date in the constraint is <tt>yyyMMdd</tt>. It is independent of the locale.
| |
| − | # The date specified in the constraint is ''included''. For example, <tt>"before 20071225"</tt> includes December 25, 2007 and every day before it.
| |
| − | # The constraint is actually represented with an instance of the <tt>org.zkoss.zul.SimpleDateConstraint</tt> class. You can retrieve the parsed beginning and ending date with the <tt>getBeginDate</tt> and <tt>getEndDate</tt> methods.
| |
| − |
| |
| − | <source lang="java" >
| |
| − | ((SimpleDateConstraint)datebox.getConstraint()).getBeginDate();
| |
| − | </source>
| |
| − |
| |
| − | === Custom Constraints ===
| |
| − | If you want to use more sophisticated constraints, you can specify an object which implements the <tt>org.zkoss.zul.Constraint</tt> interface.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <window title="Custom Constraint">
| |
| − | <zscript><![CDATA[
| |
| − | Constraint ctt = new Constraint() {
| |
| − | public void validate(Component comp, Object value) throws WrongValueException {
| |
| − | if (value =e= null || ((Integer)value).intValue() < 100)
| |
| − | throw new WrongValueException(comp, "At least 100 must be specified");
| |
| − | }
| |
| − | }
| |
| − | ]]>
| |
| − | </zscript>
| |
| − | <intbox constraint="${ctt}" />
| |
| − | </window>
| |
| − | </source>
| |
| − |
| |
| − | You create a Java class to contain your constraint, say <tt>my.EmailValidator</tt>, then reference it in the markup:
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <?taglib uri="http://www.zkoss.org/dsp/web/core" prefix="c"?>
| |
| − | <textbox constraint="${c:new('my.EmailValidator')}"/>
| |
| − | </source>
| |
| − |
| |
| − | ==== org.zkoss.zk.ui.WrongValueException ====
| |
| − | <source lang="xml" >
| |
| − | <textbox>
| |
| − | <attribute name="onChange">
| |
| − | if (!self.value.equals("good")) {
| |
| − | self.value = "try again";
| |
| − | throw new WrongValueException(self, "Not a good answer!");
| |
| − | }
| |
| − | </attribute>
| |
| − | </textbox>
| |
| − | </source>
| |
| − |
| |
| − | In the above example, we use the class <tt>org.zkoss.zk.ui.WrongValueException</tt> to denote an error. As depicted, you have to specify the first argument, which is the component that caused the error, and the second argument which is the error message.
| |
| − |
| |
| − | You could throw this exception anytime, such as when an <tt>onChange</tt> event is received as shown below.
| |
| − |
| |
| − | [[Image:FormAndInput_14.png]]
| |
| − |
| |
| − |
| |
| − | ==== Custom Way to Display the Error Messages ====
| |
| − | Instead of the default error box, you are able to provide a custom look by implementing the <tt>org.zkoss.zul.CustomConstraint</tt> interface with <tt>Constraint</tt>. <tt>CustomConstraint</tt> has one method, <tt>showCustomError</tt>, which is called when an exception is thrown or when the validation is incorrect. Here is an example,
| |
| − |
| |
| − | [[Image:FormAndInput_15.png]]
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <window title="Custom Constraint" border="normal">
| |
| − | <zscript><![CDATA[
| |
| − | class MyConst implements Constraint, CustomConstraint {
| |
| − | //Constraint//
| |
| − | public void validate(Component comp, Object value) {
| |
| − | if (value == null || ((Integer)value).intValue() < 100)
| |
| − | throw new WrongValueException(comp, "At least 100 must be specified");
| |
| − | }
| |
| − | //CustomConstraint//
| |
| − | public void showCustomError(Component comp, WrongValueException ex) {
| |
| − | errmsg.setValue(ex != null ? ex.getMessage(): "");
| |
| − | }
| |
| − | }
| |
| − | Constraint ctt = new MyConst();
| |
| − | ]]>
| |
| − | </zscript>
| |
| − | <hbox>
| |
| − | Enter a number at least 100:
| |
| − | <intbox constraint="${ctt}" />
| |
| − | <label id="errmsg" />
| |
| − | </hbox>
| |
| − | </window>
| |
| − | </source>
| |
| − |
| |
| − | ==== Improve Responsiveness ====
| |
| − | Responsiveness can be improved by validating more constraints client side. To do this, you have to implement the <tt>org.zkoss.zul.ClientConstraint</tt> interface with <tt>Constraint</tt>. If you have done all validations client side, you can return true for the <tt>isClientComplete</tt> method, and then there will be no server callback at all.
| |
| − |
| |
| − | You can also customize the display of the error message with pure JavaScript codes a the client by providing a function called <tt>Validate_errorbox</tt>. For example,
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <script type="text/javascript"><![CDATA[
| |
| − | //Running at the browser
| |
| − | window.Validate_errorbox = function (id, boxid, msg) {
| |
| − | var html = '<div style="display:none;position:absolute" id="'
| |
| − | +boxid+'">'+zk.encodeXML(msg, true)+'</div>';
| |
| − | document.body.insertAdjacentHTML("afterbegin", html);
| |
| − | return $e(boxid);
| |
| − | }
| |
| − | ]]>
| |
| − | </script>
| |
| − | </source>
| |
| − |
| |
| − | '''Note''': <tt>script</tt> specifies the script codes running at the browser, while <tt>zscript</tt> specifies codes running at the server.
| |
| − |
| |
| − | '''Note''': If <tt>CustomConstraint </tt>is also implemented, <tt>ClientConstraint</tt> will be ignored since all validations are done at the server. In other words, if you want to use <tt>ClientConstraint</tt> to improve responsiveness, overriding <tt>Validate_errorbox</tt> is the only way to customize the display of the error message.
| |
| − |
| |
| − | === The onChange Event ===
| |
| − | An input control notifies the application with the <tt>onChange</tt> event if its content is changed by the user.
| |
| − |
| |
| − | Notice that, when the <tt>onChange</tt>'s event listener is invoked, the value has been set. Thus, it is too late if you want to reject illegal value in the <tt>onChange</tt>'s event listener, unless you restore the value properly. Rather, it is recommended to use a constraint as described in the '''Custom Constraints''' section.
| |
| − |
| |
| − | === The onChanging event ===
| |
| − | An input control also notifies the application with the <tt>onChanging</tt> event, when user is changing the content.
| |
| − |
| |
| − | Notice that, when the <tt>onChanging</tt>'s listener is invoked, the value is not set yet. In other worlds, the <tt>value</tt> property is still the old value. To retrieve what the user is entering, you have to access the <tt>value</tt> property of the event as follows.
| |
| − |
| |
| − | <source lang="xml" >
| |
| − | <grid>
| |
| − | <rows>
| |
| − | <row>The onChanging textbox:
| |
| − | <textbox onChanging="copy.value = event.value"/></row>
| |
| − | <row>Instant copy:
| |
| − | <textbox id="copy" readonly="true"/></row>
| |
| − | </rows>
| |
| − | </grid>
| |
| − | </source>
| |
| − | [[Image:inputelements.png]]
| |
| − | <br/>
| |
| − | It is too early to reject an illegal value in the <tt>onChanging</tt>』s event listener, because the user may not have completed the change. Rather, it is recommended to use a constraint as described in the '''Custom Constraints''' section.
| |
| − |
| |
| − | == See Also ==
| |
| − | From ZK Forum:
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D5492%3BcategoryId%3D14%3B onChanging event not everytime fired in Combobox]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D5659%3BcategoryId%3D14%3B Datebox Problem in ZK 3.5.0]
| |
| − | *[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D5651%3BcategoryId%3D14%3B onChange-Event in Textbox doesn't get fired]
| |
| | | | |
| | {{ ZKDevelopersGuidePageFooter}} | | {{ ZKDevelopersGuidePageFooter}} |
