Package org.zkoss.stateless.sul

## Interface IInputElement<I extends IInputElement,​ValueTypeT>

- All Superinterfaces:
    `IChildrenOfInputgroup<I>`, `IComponent<I>`, `IHtmlBasedComponent<I>`, `IReadonly<I>`, `IXulElement<I>`
  All Known Subinterfaces:
    `IBandbox`, `ICombobox`, `IDatebox`, `IDateTimeFormatInputElement<I>`, `IDecimalbox`, `IDoublebox`, `IDoublespinner`, `IFormatInputElement<I,​ValueTypeT>`, `IIntbox`, `ILongbox`, `INumberInputElement<I,​ValueTypeT>`, `ISpinner`, `ITextbox`, `ITextboxBase<I>`, `ITimebox`, `ITimepicker`

      public interface IInputElement<I extends IInputElement,​ValueTypeT>
      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")
           );
       }

  Condition | Description
  --- | ---
  You can specify following values with `withConstraint(String)` to apply them
  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
    `ValueTypeT` | `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​(ValueTypeT 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
          ValueTypeT getValue()

      Returns the value of the input component.

      Default: `null`.

    - #### withValue

          I withValue​(@Nullable
                      ValueTypeT 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