ZK Component Reference/Base Components/InputElement

Input Element

• Demonstration: N/A
• Java API: InputElement
• JavaScript API: InputWidget

Employment/Purpose

InputElement is a super class for components which provie user key input, such as textbox, intbox, decimalbox, doublebox, datebox, timebox, spinner, combobox, and bandbox.

Some features are implemented in this class, such as constraint, disabled, maxlength, name, readonly, etc.

You sholuld not deirectly use this class, please use the inherited class.

Example

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

Validation

There are two ways to validate the value entered by an user: implementing Constraint or throwing WrongValueException.

Constraint

An input element can be associated with a constraint (Constraint) to validate the value entered by an user. There is a default implementation called SimpleConstraint that can handle many conditions. If it is not enough, you can implement your own constraint, or throwing WrongValueException as described in the next section.

public class EventNumberConstraint implements Constraint {
	public void validate(Component comp, Object value)
	throws WrongValueException {
		if (value != null && (value.intValue() & 1) != 0) //assume used with intbox
			throw new WrongValueException(comp, "Only even numbers are allowed, not "+value);
	}
}

WrongValueException

In additions to throwing WrongValueException in Constraint.validate(Component, Object), you can throw WrongValueException in other situation. For example, you can validate the user name and password when the user presses the login button. For example,

public class FooComposer extends GenericForwardComposer {
  private Textbox username;
  private Textbox password;

  public void onClick$login() {
    username.clearErrorMessage(); //important to clear the previous error, if any
    if (examine(username, password)) {
      //success
    } else {
      throw new WrongValueException(username, "Not a valid username or password. Please retry.");
    }
  }
}

However, notice that you have to clear the error message manually by invoking InputElement.clearErrorMessage(). Otherwise, the error message will remain there unless Textbox.setValue(String) is called.

Properties

Inplace

All input elements can have the in-place-editing functionality, like the combobox, textbox, datebox, and so on.

<textbox inplace="true"/>
<combobox inplace="true"/>
<datebox inplace="true"/>

[Since 5.0.0]

Supported Events

Name	Event Type
onChange	Event: InputEvent Denotes the content of an input component has been modified by the user.
onChanging	Event: InputEvent Denotes that user is changing the content of an input component. Notice that the component's content (at the server) won't be changed until onChange is received. Thus, you have to invoke the getValue method in the InputEvent class to retrieve the temporary value.
onSelection	Event: SelectionEvent Denotes that user is selecting a portion of the text of an input component. You can retrieve the start and end position of the selected text by use of the getStart and getEnd methods.
onFocus	Event: Event Denotes when a component gets the focus. Remember event listeners execute at the server, so the focus at the client might be changed when the event listener for onFocus got executed.
onBlur	Event: Event Denotes when a component loses the focus. Remember event listeners execute at the server, so the focus at the client might be changed when the event listener for onBlur got executed.
onError	Event: ErrorEvent Denotes when a component caused a validation error.

Supported Children

*None

Use cases

Version	Description	Example Location

Version History

Version	Date	Content