All Superinterfaces:: IChildrenOfInputgroup, IComponent, IHtmlBasedComponent, IReadonly, IXulElement

All Known Subinterfaces:: IBandbox, ICombobox, IDatebox, IDateTimeFormatInputElement, IDecimalbox, IDoublebox, IDoublespinner, IFormatInputElement<I,ValueType>, IIntbox, ILongbox, INumberInputElement<I,ValueType>, ISpinner, ITextbox, ITextboxBase, ITimebox, ITimepicker

public interface IInputElement<I extends IInputElement,ValueType>
extends IXulElement<I>, IReadonly<I>, IChildrenOfInputgroup<I>

Immutable InputElement interface.

A skeletal implementation of an input box.

Support @Action

Name	Action Type
onChange	ActionData: `InputData` Denotes the content of an input component has been modified by the user.
onChanging	ActionData: `InputData` Denotes that user is changing the content of an input component.
onSelection	ActionData: `SelectionData` 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	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	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	ActionData: `ErrorData` Denotes when a component caused a validation error.

Example

 @RichletMapping("example")
 public IComponent example() {
     return IGrid.DEFAULT.withRows(
         IRows.of(
             IRow.of(
                 ILabel.of("UserName: "),
                 ITextbox.of("Jerry").withWidth("150px")
             ),
             IRow.of(
                 ILabel.of("Password: "),
                 ITextbox.of("foo").withType("password").withWidth("150px")
             ),
             IRow.of(
                 ILabel.of("Phone: "),
                 IIntbox.of(12345678).withConstraint("no negative, no zero").withWidth("150px")
             ),
             IRow.of(
                 ILabel.of("Weight: "),
                 IDecimalbox.of("154.32").withFormat("###.##").withWidth("150px")
             ),
             IRow.of(
                 ILabel.of("Birthday: "),
                 IDatebox.ofId("db").withWidth("150px")
             ),
             IRow.of(
                 ILabel.of("E-mail: "),
                 ITextbox.of("zk@zkoss.org")
                     .withConstraint("/.+@.+\\.[a-z]+/: Please enter an e-mail address").withWidth("150px")
             )
         )
     );
 }

Built-in Constraints

To use the default constraint, you could specify a list of conditions in withConstraint(String), such as no positive and no empty.

For example,

 @RichletMapping("/builtinConstraints")
 public IComponent builtinConstraints() {
     return IDiv.of(
         ITextbox.ofConstraint("no empty"),
         IIntbox.ofConstraint("no negative, no zero")
     );
 }

You can specify following values with `withConstraint(String)` to apply them
Condition	Description
no empty	Empty is not allowed.
no future	Date in the future is not allowed.
no negative	Negative numbers are not allowed.
no past	Date in the past is not allowed.
no positive	Postive numbers are not allowed.
no today	Today is not allowed.
no zero	Zero numbers are not allowed.
between yyyyMMdd and yyyyMMdd	Date only allowed between the specified range. The format must be `yyyyMMdd`, such as `IDatebox.ofConstraint("between 20211225 and 20211203");`
after yyyyMMdd	Date only allowed after (and including) the specified date. The format must be `yyyyMMdd`, such as `IDatebox.ofConstraint("after 20211225");`
before yyyyMMdd	Date only allowed before (and including) the specified date. The format must be `yyyyMMdd`, such as `IDatebox.ofConstraint("before 20211225");`
end_before end_after after_start after_end ...	Specifies the position of the error box. Please refer to `IPopup` for all allowed position. `ITextbox.ofConstraint("no empty, end_after"); ITextbox.ofConstraint("no empty, start_before");`

Regular Expression

To specify a regular expression, you could have to use / to enclose the regular expression as follows.

 
 ITextbox.ofConstraint("/.+@.+\\.[a-z]+/");

Flags

To specify the flags to the regular expression, you could add the flags after the ending slash of the regular expression.

For example, If you want to enable case-insensitive matching, you could add the flag as bellow.

 
 ITextbox.ofConstraint("/[A-Z]{3}/i");

The flags supported:

flags	Description
i	ignore case
m	multiline
s	dotAll
u	unicode

Note: the regular expression will always using global match no matter the g flag is added or not.

Multiple Constraints

Notice that it is allowed to mix regular expression with other constraints by separating them with a comma.

If you prefer to display an application dependent message instead of default one, you could append the constraint with colon and the message you want to display when failed.

 
 ITextbox.ofConstraint("/.+@.+\\.[a-z]+/: e-mail address only");
 IDatebox.ofConstraint("no empty, no future: now or never");

of course, it supports multiple custom messages

 
 IIntbox.ofConstraint("no negative: forbid negative, no positive: forbid positive");

i18n Error Message

 
 ITextbox.ofConstraint("/.+@.+\\.[a-z]+/: " + CommonFns.getLabel("err.email.required"))

Escape a Comma

If you want to write a longer sentence with comma separator, you can enclose your customized sentence with curly braces

 
 ITextbox.ofConstraint("no empty: {Sorry, no empty allowed}, /.+@.+\\.[a-z]+/: email only")

Custom Constraint

If you want a custom constraint, you could register an onChange action to validate the input value

For example,

 @RichletMapping("/customConstraint")
 public IComponent customConstraint() {
     return ITextbox.DEFAULT.withAction(this::doCustomConstraint);
 }

 @Action(type = Events.ON_CHANGE)
 public void doCustomConstraint(UiAgent uiAgent, Self self, InputData inputData) {
     String value = inputData.getValue();
     if (value != null && new Integer(value).intValue() % 2 == 1) {
         uiAgent.smartUpdate(self, new ITextbox.Updater().errorMessage("Only even numbers are allowed, not " + value));
     }
 }

If the validation fails, just use UiAgent.smartUpdate(Locator, SmartUpdater) to update the error message of the ITextbox by its updater.

Author:: katherine

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method	Description
`default int`	`getCols()`	Returns the cols which determines the visible width, in characters.
`java.lang.String`	`getConstraint()`	Returns the client constraint to validate the value entered by a user. if any.
`java.lang.String`	`getErrorboxIconSclass()`	Returns the class name of the custom style applied to the errorbox icon of this component.
`java.lang.String`	`getErrorboxSclass()`	Returns the class name of the custom style applied to the errorbox of this component.
`java.lang.String`	`getErrorMessage()`	Returns the error message that is set by `withErrorMessage(String)`
`java.util.Map<java.lang.String,java.lang.String>`	`getInputAttributes()`	Returns the additional attributes which is set by `withInputAttributes(Map)`
`default boolean`	`getInstant()`	Returns `true` if `onChange` action is sent as soon as user types in the input component.
`default int`	`getMaxlength()`	Returns the maxlength.
`java.lang.String`	`getName()`	Returns the name of this component.
`java.lang.String`	`getPlaceholder()`	Returns a short hint that describes the expected value of an input component
`ValueType`	`getValue()`	Returns the value of the input component.
`default boolean`	`isDisabled()`	Returns whether it is disabled.
`default boolean`	`isInplace()`	Returns whether enable the inplace-editing.
`I`	`withCols(int cols)`	Returns a copy of `this` immutable component with the specified `cols`.
`I`	`withConstraint(java.lang.String constraint)`	Returns a copy of `this` immutable component with the specified `constraint`.
`I`	`withDisabled(boolean disabled)`	Returns a copy of `this` immutable component with the specified `disabled`.
`I`	`withErrorboxIconSclass(java.lang.String errorboxIconSclass)`	Returns a copy of `this` immutable component with the specified `errorboxIconSclass`.
`I`	`withErrorboxSclass(java.lang.String errorboxSclass)`	Returns a copy of `this` immutable component with the specified `errorboxSclass`.
`I`	`withErrorMessage(java.lang.String errorMessage)`	Returns a copy of `this` immutable component with the specified `errorMessage`.
`I`	`withInplace(boolean inplace)`	Returns a copy of `this` immutable component with the specified `inplace`.
`I`	`withInputAttributes(java.util.Map<java.lang.String,? extends java.lang.String> inputAttributes)`	Returns a copy of `this` immutable component with the specified `inputAttributes`.
`I`	`withInstant(boolean instant)`	Returns a copy of `this` immutable component with the specified `instant`.
`I`	`withMaxlength(int maxlength)`	Returns a copy of `this` immutable component with the specified `maxlength`.
`I`	`withName(java.lang.String name)`	Returns a copy of `this` immutable component with the specified `name`.
`I`	`withPlaceholder(java.lang.String placeholder)`	Returns a copy of `this` immutable component with the specified `placeholder`.
`I`	`withValue(ValueType value)`	Returns a copy of `this` immutable component with the specified `value`.

Methods inherited from interface org.zkoss.stateless.sul.IComponent
getAction, getActions, getClientAttributes, getId, getMold, getWidgetClass, getWidgetListeners, getWidgetOverrides, isVisible, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withActions, withActions, withClientAttribute, withClientAttributes, withId, withMold, withVisible, withWidgetClass, withWidgetListener, withWidgetListeners, withWidgetOverride, withWidgetOverrides

Methods inherited from interface org.zkoss.stateless.sul.IHtmlBasedComponent
getClientAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTabindex, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZIndex, isFocus, withClientAction, withDraggable, withDroppable, withFocus, withHeight, withHflex, withLeft, withRenderdefer, withSclass, withStyle, withTabindex, withTabindex, withTooltiptext, withTop, withVflex, withWidth, withZclass, withZIndex

Methods inherited from interface org.zkoss.stateless.sul.IReadonly
isReadonly, withReadonly

Methods inherited from interface org.zkoss.stateless.sul.IXulElement
getContext, getCtrlKeys, getPopup, getTooltip, withContext, withCtrlKeys, withPopup, withTooltip

Method Detail

getName
```
@Nullable
java.lang.String getName()
```
Returns the name of this component.
Default: null.
Don't use this method if your application is purely based on ZK's event-driven model.
The name is used only to work with "legacy" Web application that handles user's request by servlets. It works only with HTTP/HTML-based browsers. It doesn't work with other kind of clients.

withName
```
I withName(@Nullable
           java.lang.String name)
```
Returns a copy of this immutable component with the specified name.
Sets the name of this component.
Don't use this method if your application is purely based on ZK's event-driven model.
The name is used only to work with "legacy" Web application that handles user's request by servlets. It works only with HTTP/HTML-based browsers. It doesn't work with other kind of clients.

Parameters:

name - The name of this component.
Default: null.

Returns:

A modified copy of the this object

getPlaceholder
```
@Nullable
java.lang.String getPlaceholder()
```
Returns a short hint that describes the expected value of an input component
Default: null

withPlaceholder
```
I withPlaceholder(@Nullable
                  java.lang.String placeholder)
```
Returns a copy of this immutable component with the specified placeholder.
Sets the short hint that is displayed in the input component before the user enters a value.

Parameters:

placeholder - The short hint that describes the expected value of an input component.
Default: null.

Returns:

A modified copy of the this object

getInputAttributes
```
@Nullable
java.util.Map<java.lang.String,java.lang.String> getInputAttributes()
```
Returns the additional attributes which is set by withInputAttributes(Map)
Default: null.

withInputAttributes
```
I withInputAttributes(@Nullable
 java.util.Map<java.lang.String,? extends java.lang.String> inputAttributes)
```
Returns a copy of this immutable component with the specified inputAttributes.
Sets some additional attributes to the input HTML tag of the component at client.

Parameters:

inputAttributes - The inputAttributes can take a Map with attribute names as the keys or a String separate by ";" and follow the name=value rule.
Default: null.

Returns:

A modified copy of the this object

getValue
```
@Nullable
ValueType getValue()
```
Returns the value of the input component.
Default: null.

withValue
```
I withValue(@Nullable
            ValueType value)
```
Returns a copy of this immutable component with the specified value.
Sets the value of the input component.

Parameters:

value - The value of the input component.
Default: null.

Returns:

A modified copy of the this object

getConstraint
```
@Nullable
java.lang.String getConstraint()
```
Returns the client constraint to validate the value entered by a user. if any.
Default: null

withConstraint

I withConstraint(@Nullable
                 java.lang.String constraint)

Returns a copy of this immutable component with the specified constraint.

Sets the client constraint to validate the value entered by a user; you can specify the following values or Regular Expression.

Condition	Description
no empty	Empty is not allowed.
no future	Date in the future is not allowed.
no negative	Negative numbers are not allowed.
no past	Date in the past is not allowed.
no positive	Postive numbers are not allowed.
no today	Today is not allowed.
no zero	Zero numbers are not allowed.
between yyyyMMdd and yyyyMMdd	Date only allowed between the specified range. The format must be `yyyyMMdd`, such as `IDatebox.ofConstraint("between 20211225 and 20211203");`
after yyyyMMdd	Date only allowed after (and including) the specified date. The format must be `yyyyMMdd`, such as `IDatebox.ofConstraint("after 20211225");`
before yyyyMMdd	Date only allowed before (and including) the specified date. The format must be `yyyyMMdd`, such as `IDatebox.ofConstraint("before 20211225");`
end_before end_after after_start after_end ...	Specifies the position of the error box. Please refer to `IPopup` for all allowed position. `ITextbox.ofConstraint("no empty, end_after"); ITextbox.ofConstraint("no empty, start_before");`

Parameters:: constraint - The client constraint of the component.
Default: null.
Returns:: A modified copy of the this object

getErrorboxSclass
```
@Nullable
java.lang.String getErrorboxSclass()
```
Returns the class name of the custom style applied to the errorbox of this component.
Default: null

withErrorboxSclass
```
I withErrorboxSclass(@Nullable
                     java.lang.String errorboxSclass)
```
Returns a copy of this immutable component with the specified errorboxSclass.
Sets the class name of the custom style to be applied to the errorbox of this component.

Parameters:

errorboxSclass - The class name of the custom style.
Default: null.

Returns:

A modified copy of the this object

getErrorboxIconSclass
```
@Nullable
java.lang.String getErrorboxIconSclass()
```
Returns the class name of the custom style applied to the errorbox icon of this component.
Default: null

withErrorboxIconSclass
```
I withErrorboxIconSclass(@Nullable
                         java.lang.String errorboxIconSclass)
```
Returns a copy of this immutable component with the specified errorboxIconSclass.
Sets the class name of the custom style to be applied to the icon of the errorbox of this component.

Parameters:

errorboxIconSclass - The class name of the custom style for the icon of the errorbox.
Default: null.

Returns:

A modified copy of the this object

isDisabled
```
default boolean isDisabled()
```
Returns whether it is disabled.
Default: false.

withDisabled
```
I withDisabled(boolean disabled)
```
Returns a copy of this immutable component with the specified disabled.
Sets whether it is disabled.

Parameters:

disabled - true to disable this input component.
Default: false.

Returns:

A modified copy of the this object

isInplace
```
default boolean isInplace()
```
Returns whether enable the inplace-editing.
default: false.

withInplace
```
I withInplace(boolean inplace)
```
Returns a copy of this immutable component with the specified inplace.
Sets to enable the inplace-editing function that the look and feel is like a label.

Parameters:

inplace - true to enable the inplace-editing fuction.
Default: false.

Returns:

A modified copy of the this object

getMaxlength
```
default int getMaxlength()
```
Returns the maxlength.
Default: 0 (non-positive means unlimited).

withMaxlength
```
I withMaxlength(int maxlength)
```
Returns a copy of this immutable component with the specified maxlength.
Sets the maxlength.
The length includes the format, if specified.

Parameters:

maxlength - The max length to display.
Default: 0.

Returns:

A modified copy of the this object

getCols
```
default int getCols()
```
Returns the cols which determines the visible width, in characters.
Default: 0 (non-positive means the same as browser's default).

withCols
```
I withCols(int cols)
```
Returns a copy of this immutable component with the specified cols.
Sets the cols which determines the visible width, in characters.

Parameters:

cols - The cols which determines the visible width
Default: 0.

Returns:

A modified copy of the this object

getInstant
```
default boolean getInstant()
```
Returns true if onChange action is sent as soon as user types in the input component.
Default: false

withInstant
```
I withInstant(boolean instant)
```
Returns a copy of this immutable component with the specified instant.
Sets the instant attribute. When the attribute is true, onChange action will be fired as soon as user type in the input component.

Parameters:

instant - true to send the action ASAP.
Default: false.

Returns:

A modified copy of the this object

getErrorMessage
```
@Nullable
java.lang.String getErrorMessage()
```
Returns the error message that is set by withErrorMessage(String)
Default: null

withErrorMessage
```
I withErrorMessage(@Nullable
                   java.lang.String errorMessage)
```
Returns a copy of this immutable component with the specified errorMessage.
Associates an error message to this input. It will cause the given error message to be shown at the client.

Parameters:

errorMessage - The error message to show at client.
Default: null.

Returns:

A modified copy of the this object

Interface IInputElement<I extends IInputElement,​ValueType>

Support @Action

Example

Built-in Constraints

Regular Expression

Flags

Multiple Constraints

i18n Error Message

Escape a Comma

Custom Constraint

Method Summary

Methods inherited from interface org.zkoss.stateless.sul.IComponent

Methods inherited from interface org.zkoss.stateless.sul.IHtmlBasedComponent

Methods inherited from interface org.zkoss.stateless.sul.IReadonly

Methods inherited from interface org.zkoss.stateless.sul.IXulElement

Method Detail

getName

withName

getPlaceholder

withPlaceholder

getInputAttributes

withInputAttributes

getValue

withValue

getConstraint

withConstraint

getErrorboxSclass

withErrorboxSclass

getErrorboxIconSclass

withErrorboxIconSclass

isDisabled

withDisabled

isInplace

withInplace

getMaxlength

withMaxlength

getCols

withCols

getInstant

withInstant

getErrorMessage

withErrorMessage

Interface IInputElement<I extends IInputElement,ValueType>