Package org.zkoss.stateless.sul

## Interface IComponent<R extends IComponent>

- All Known Subinterfaces:
    `IA<I>`, `IAbsolutechildren<I>`, `IAbsolutelayout`, `IAnchornav<I>`, `IAnyGroup<I>`, `IArea`, `IAudio`, `IAuxhead`, `IAuxheader<I>`, `IBandbox`, `IBandpopup<I>`, `IBarcode`, `IBarcodescanner`, `IBiglistbox`, `IBorderlayout`, `IButton`, `IButtonBase<I>`, `ICalendar`, `ICamera`, `ICaption<I>`, `ICardlayout<I>`, `ICascader`, `ICell<I>`, `ICenter<I>`, `ICheckbox`, `ICheckboxBase<I>`, `IChildrenOfInputgroup<I>`, `IChildrenOfMenupopup<I>`, `IChildrenOfNavbar<I>`, `IChildrenOfPanel<I>`, `IChildrenOfTab<I>`, `IChosenbox`, `ICoachmark<I>`, `IColorbox`, `IColumn<I>`, `IColumnchildren<I>`, `IColumnlayout`, `IColumns`, `ICombobox`, `ICombobutton`, `IComboitem`, `ICropper`, `IDatebox`, `IDateTimeFormatInputElement<I>`, `IDecimalbox`, `IDetail<I>`, `IDetailChild<I>`, `IDiv<I>`, `IDoublebox`, `IDoublespinner`, `IDrawer<I>`, `IDropupload`, `IEast<I>`, `IFileupload`, `IFisheye`, `IFisheyebar`, `IFoot`, `IFooter<I>`, `IFooterElement<I>`, `IFormatInputElement<I,​ValueTypeT>`, `IFrozen<I>`, `IGoldenLayout`, `IGoldenPanel<I>`, `IGrid`, `IGridComposite<I>`, `IGroup<I>`, `IGroupbox<I>`, `IGroupChild<I>`, `IGroupfoot<I>`, `IGroupfootChild<I>`, `IHeaderElement<I>`, `IHeadersElement<I>`, `IHlayout<I>`, `IHtml`, `IHtmlBasedComponent<I>`, `IIframe`, `IImage`, `IImageBase<I>`, `IImagemap`, `IInputElement<I,​ValueTypeT>`, `IInputgroup`, `IIntbox`, `ILabel`, `ILabelElement<I>`, `ILabelImageElement<I>`, `ILayout<I>`, `ILayoutRegion<I>`, `ILineitem<I>`, `ILinelayout`, `IListbox`, `IListboxComposite<I>`, `IListcell<I>`, `IListfoot`, `IListfooter<I>`, `IListgroup`, `IListgroupChild<I>`, `IListgroupfoot`, `IListgroupfootChild<I>`, `IListhead`, `IListheader<I>`, `IListitem`, `IListitemBase<I>`, `ILongbox`, `IMenu`, `IMenubar`, `IMenuitem`, `IMenupopup`, `IMenuseparator`, `IMeshComposite<I>`, `IMeshElement<I>`, `IMultislider`, `INav`, `INavbar`, `INavitem`, `INavseparator`, `INorth<I>`, `INumberInputElement<I,​ValueTypeT>`, `IOrganigram`, `IOrgchildren`, `IOrgitem`, `IOrgitemComposite<I>`, `IOrgnode<I>`, `IPaging`, `IPanel`, `IPanelchildren<I>`, `IPdfviewer`, `IPopup<I>`, `IPopupBase<I>`, `IPortalchildren`, `IPortallayout`, `IProgressmeter`, `IRadio`, `IRadiogroup<I>`, `IRangeslider`, `IRangesliderBase<I>`, `IRating`, `IRow<I>`, `IRowBase<I>`, `IRowchildren<I>`, `IRowlayout`, `IRows`, `IScript`, `IScrollview<I>`, `ISearchbox`, `ISelectbox`, `ISeparator`, `ISeparatorBase<I>`, `ISignature`, `ISlider`, `ISliderbuttons`, `ISouth<I>`, `ISpace`, `ISpan<I>`, `ISpinner`, `ISplitlayout<I>`, `IStep`, `IStepbar`, `IStyle`, `ITab`, `ITabbox`, `ITabboxComposite<I>`, `ITablechildren<I>`, `ITablelayout`, `ITabpanel<I>`, `ITabpanels`, `ITabs`, `ITbeditor`, `ITextbox`, `ITextboxBase<I>`, `ITimebox`, `ITimepicker`, `ITimer`, `IToolbar<I>`, `IToolbarbutton`, `ITrack`, `ITree`, `ITreecell<I>`, `ITreechildren`, `ITreecol<I>`, `ITreecols`, `ITreeComposite<I>`, `ITreefoot`, `ITreefooter<I>`, `ITreeitem`, `ITreeitemComposite<I>`, `ITreerow`, `IVideo`, `IVlayout<I>`, `IWest<I>`, `IWindow<I>`, `IXulElement<I>`

      public interface IComponent<R extends IComponent>

  Immutable `Component` interface.

  Provides a set of immutable APIs of a ZK component to create a same result as ZK component to client side, and by hooking an `action` or multiple `actions` on a client widget triggers a user action to server to handle it in a stateless HTTP request protocol, and then the developer can manipulate the client state at server by an action handler.

  For example,

       @RichletMapping("")
       public IComponent index() {
           return IVlayout.of(ITextbox.ofId("msg"),
               IButton.of("Submit").withAction(this::doSubmit));
       }

       @Action(type = Events.ON_CLICK)
       public void doSubmit(@ActionVariable(targetId="msg", field="value") String msg) {
           Clients.alert("Hello " + msg);
       }

  As you can see, the `@ActionVariable()` annotation declared on the `doSubmit()` method handler is a way to receive the client widget state at server, in this case, the `msg` value is the value of the `ITextbox`, which the user types if any.

  Note: It's convenient to use `doSubmit(String msg)` directly if the Javac compiler with `-parameters` to generate metadata for reflection on method parameters.

  Author:
    jumperchen
  See Also:
    `ActionVariable`, `Action`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `ActionHandler` | `getAction()` | Returns the `ActionHandler` if any.
    `java.util.List<ActionHandler>` | `getActions()` | Returns all the `ActionHandler`s if any.
    `java.util.Map<java.lang.String,​java.lang.String>` | `getClientAttributes()` | Returns the client DOM attributes.
    `default java.lang.String` | `getId()` | Returns the ID.
    `default java.lang.String` | `getMold()` | Returns the mold used to render this component.
    `java.lang.String` | `getWidgetClass()` | Returns the client widget class which belongs to this component.
    `java.util.Map<java.lang.String,​java.lang.String>` | `getWidgetListeners()` | Returns the client widget listeners.
    `java.util.Map<java.lang.String,​java.lang.String>` | `getWidgetOverrides()` | Returns the mapping of the script and the function definition to override widget's methods and attributes, or null.
    `default boolean` | `isVisible()` | Returns whether this component is visible at client.
    `R` | `withAction​(ActionHandler action)` | Returns a copy of `this` immutable component with the specified `action`.
    `default R` | `withAction​(ActionHandler0 action)` | Returns a copy of `this` immutable component with the specified `action`.
    `default <A> R` | `withAction​(ActionHandler1<A> action)` | Returns a copy of `this` immutable component with the specified `action`.
    `default <A,​B> R` | `withAction​(ActionHandler2<A,​B> action)` | Returns a copy of `this` immutable component with the specified `action`.
    `default <A,​B,​C> R` | `withAction​(ActionHandler3<A,​B,​C> action)` | Returns a copy of `this` immutable component with the specified `action`.
    `default <A,​B,​C,​D> R` | `withAction​(ActionHandler4<A,​B,​C,​D> action)` | Returns a copy of `this` immutable component with the specified `action`.
    `default <A,​B,​C,​D,​E> R` | `withAction​(ActionHandler5<A,​B,​C,​D,​E> action)` | Returns a copy of `this` immutable component with the specified `action`.
    `default <A,​B,​C,​D,​E,​F> R` | `withAction​(ActionHandler6<A,​B,​C,​D,​E,​F> action)` | Returns a copy of `this` immutable component with the specified `action`.
    `default <A,​B,​C,​D,​E,​F,​G> R` | `withAction​(ActionHandler7<A,​B,​C,​D,​E,​F,​G> action)` | Returns a copy of `this` immutable component with the specified `action`.
    `default <A,​B,​C,​D,​E,​F,​G,​H> R` | `withAction​(ActionHandler8<A,​B,​C,​D,​E,​F,​G,​H> action)` | Returns a copy of `this` immutable component with the specified `action`.
    `default <A,​B,​C,​D,​E,​F,​G,​H,​I> R` | `withAction​(ActionHandler9<A,​B,​C,​D,​E,​F,​G,​H,​I> action)` | Returns a copy of `this` immutable component with the specified `action`.
    `R` | `withActions​(java.lang.Iterable<? extends ActionHandler> actions)` | Returns a copy of `this` immutable component with the specified `actions`.
    `R` | `withActions​(ActionHandler... actions)` | Returns a copy of `this` immutable component with the specified `actions`.
    `default R` | `withClientAttribute​(java.lang.String name, java.lang.String value)` | Returns a copy of `this` immutable component with the specified `name` and `value`.
    `R` | `withClientAttributes​(java.util.Map<java.lang.String,​? extends java.lang.String> clientAttributes)` | Returns a copy of `this` immutable component with the specified `clientAttributes`.
    `R` | `withId​(java.lang.String id)` | Returns a copy of `this` immutable component with the specified `ID`.
    `R` | `withMold​(java.lang.String mold)` | Returns a copy of `this` immutable component with the specified `mold`.
    `R` | `withVisible​(boolean visible)` | Returns a copy of `this` immutable component with the specified `visible`.
    `R` | `withWidgetClass​(java.lang.String widgetClass)` | Returns a copy of `this` immutable component with the specified `widgetClass`.
    `default R` | `withWidgetListener​(java.lang.String eventName, java.lang.String script)` | Returns a copy of `this` immutable component with the specified `eventName` and `script`.
    `R` | `withWidgetListeners​(java.util.Map<java.lang.String,​? extends java.lang.String> widgetListeners)` | Returns a copy of `this` immutable component with the specified `widgetListeners`.
    `default R` | `withWidgetOverride​(java.lang.String name, java.lang.String script)` | Returns a copy of `this` immutable component with the specified `name` and `script`.
    `R` | `withWidgetOverrides​(java.util.Map<java.lang.String,​? extends java.lang.String> widgetOverrides)` | Returns a copy of `this` immutable component with the specified `widgetOverrides`.

- - ### Method Detail

    - #### getId

          default java.lang.String getId()

      Returns the ID.

      Default: `""` (an empty string; it means no ID at all).
      Note: Unlike ZK Component, there is no ID Space in Stateless Component, so the `ID` should be unique within a Desktop Scope, aka a browser page.

    - #### withId

          R withId​(java.lang.String id)

      Returns a copy of `this` immutable component with the specified `ID`.

      Note: Unlike ZK Component, there is no ID Space in Stateless Component, so the `ID` should be unique within a Desktop Scope, aka a browser page.

      Parameters:
        `id` - The identifier. You could specify null or an empty string to remove ID.

        Default: `""` (an empty string; it means no ID at all).

      Returns:
        A modified copy of the `this` object

    - #### getWidgetClass

          java.lang.String getWidgetClass()

      Returns the client widget class which belongs to this component.

    - #### withWidgetClass

          R withWidgetClass​(java.lang.String widgetClass)

      Returns a copy of `this` immutable component with the specified `widgetClass`.
      Parameters:
        `widgetClass` - The client widget class (a.k.a., the widget type). The widget class is a JavaScript class, including the package name.
        For example, `"zul.wnd.Window"`.
      Returns:
        A modified copy of the `this` object

    - #### getAction

          @Nullable
          ActionHandler getAction()

      Returns the `ActionHandler` if any.

      Default: `null`

    - #### getActions

          @Nullable
          java.util.List<ActionHandler> getActions()

      Returns all the `ActionHandler`s if any.

      Default: `null`

    - #### withActions

          R withActions​(@Nullable
                        ActionHandler... actions)

      Returns a copy of `this` immutable component with the specified `actions`.

      To register multiple action handler, the action type can be one of the `types` or the types in `org.zkoss.stateless.action.ActionTypeEx`
      For example,

           @RichletMapping("")
           public IComponent index() {
               return ICheckbox.ofId("myCheckbox").withActions(ActionType.onCheck(this::doMyCheck),
                   ActionType.onRightClick(this::doMyRightClick), ...);
           }

           public void doMyCheck() {
                  }

           public void doMyRightClick() {
                  }

      Note: The `withActions()` won't overwrite the one returned from `getAction()`, which is convenient for registering a single action.

      Parameters:
        `actions` - The multiple actions to register with different `ActionTypes`
      Returns:
        A modified copy of `this` object
      See Also:
        `withAction(ActionHandler)`, `withActions(Iterable)`

    - #### withActions

          R withActions​(@Nullable
                        java.lang.Iterable<? extends ActionHandler> actions)

      Returns a copy of `this` immutable component with the specified `actions`.
      Parameters:
        `actions` - The multiple actions to register with different `ActionType`s
      Returns:
        A modified copy of `this` object
      See Also:
        `withActions(ActionHandler...)`

    - #### isVisible

          default boolean isVisible()

      Returns whether this component is visible at client.

      Default: `true`

    - #### withVisible

          R withVisible​(boolean visible)

      Returns a copy of `this` immutable component with the specified `visible`.
      Parameters:
        `visible` - Sets whether `this` component is visible at client.

        Default: `true`

      Returns:
        A modified copy of `this` object

    - #### getMold

          default java.lang.String getMold()

      Returns the mold used to render this component.

      Default: `"default"`

    - #### withMold

          R withMold​(java.lang.String mold)

      Returns a copy of `this` immutable component with the specified `mold`.
      Parameters:
        `mold` - Sets the mold to render `this` component.

        Default: `"default"`

        , if `null` or an empty string `""`, the `"default"` value is assumed.
      Returns:
        A modified copy of `this` object

    - #### withAction

          R withAction​(@Nullable
                       ActionHandler action)

      Returns a copy of `this` immutable component with the specified `action`.

      To register a single action handler, the action type can be one of the `types` or the types in `org.zkoss.stateless.action.ActionTypeEx`
      For example, (with a specific `AcitonType.onClick()`)

           @RichletMapping("")
           public IComponent index() {
               return ICheckbox.ofId("myCheckbox").withAction(ActionType.onClick(this::doMyClick));
           }

           public void doMyClick() {
                  }

      Or with `@Action` annotation on a method, for example,

           @RichletMapping("")
           public IComponent index() {
               return ICheckbox.ofId("myCheckbox").withAction(this::doMyClick);
           }

           @Action(type = Events.ON_CLICK)
           public void doMyClick() {
                  }

      As you can see above, both ways are the same result to register a single action handler to an immutable component, but the priority of an action type of the first one with `ActionType.onClick()` is higher than the second one with `@Action()` annotation, in other words, the action type can be overwritten by any `types` or the types in `org.zkoss.stateless.action.ActionTypeEx` with the syntax `withAction(ActionType.onClick())`. It's convenient to share one method handler for multiple action types.

      Note: The `withAction()` won't overwrite any one returned from `getActions()`, which is convenient for registering multiple actions.

      Parameters:
        `action` - A new action of `ActionType` to register (can be `null`)
      Returns:
        A modified copy of the `this` object
      See Also:
        `ActionHandler`

    - #### withAction

          default R withAction​(@Nullable
                               ActionHandler0 action)

      Returns a copy of `this` immutable component with the specified `action`.
      Parameters:
        `action` - A new action of `ActionType` to register (can be `null`)
      Returns:
        A modified copy of the `this` object
      See Also:
        `ActionHandler0`, `withAction(ActionHandler)`

    - #### withAction

          default <A> R withAction​(@Nullable
                                   ActionHandler1<A> action)

      Returns a copy of `this` immutable component with the specified `action`.
      Parameters:
        `action` - A new action of `ActionType` to register (can be `null`)
      Returns:
        A modified copy of the `this` object
      See Also:
        `ActionHandler1`, `withAction(ActionHandler)`

    - #### withAction

          default <A,​B> R withAction​(@Nullable
                                           ActionHandler2<A,​B> action)

      Returns a copy of `this` immutable component with the specified `action`.
      Parameters:
        `action` - A new action of `ActionType` to register (can be `null`)
      Returns:
        A modified copy of the `this` object
      See Also:
        `ActionHandler2`, `withAction(ActionHandler)`

    - #### withAction

          default <A,​B,​C> R withAction​(@Nullable
                                                   ActionHandler3<A,​B,​C> action)

      Returns a copy of `this` immutable component with the specified `action`.
      Parameters:
        `action` - A new action of `ActionType` to register (can be `null`)
      Returns:
        A modified copy of the `this` object
      See Also:
        `ActionHandler3`, `withAction(ActionHandler)`

    - #### withAction

          default <A,​B,​C,​D> R withAction​(@Nullable
                                                           ActionHandler4<A,​B,​C,​D> action)

      Returns a copy of `this` immutable component with the specified `action`.
      Parameters:
        `action` - A new action of `ActionType` to register (can be `null`)
      Returns:
        A modified copy of the `this` object
      See Also:
        `ActionHandler4`, `withAction(ActionHandler)`

    - #### withAction

          default <A,​B,​C,​D,​E> R withAction​(@Nullable
                                                                   ActionHandler5<A,​B,​C,​D,​E> action)

      Returns a copy of `this` immutable component with the specified `action`.
      Parameters:
        `action` - A new action of `ActionType` to register (can be `null`)
      Returns:
        A modified copy of the `this` object
      See Also:
        `ActionHandler5`, `withAction(ActionHandler)`

    - #### withAction

          default <A,​B,​C,​D,​E,​F> R withAction​(@Nullable
                                                                           ActionHandler6<A,​B,​C,​D,​E,​F> action)

      Returns a copy of `this` immutable component with the specified `action`.
      Parameters:
        `action` - A new action of `ActionType` to register (can be `null`)
      Returns:
        A modified copy of the `this` object
      See Also:
        `ActionHandler6`, `withAction(ActionHandler)`

    - #### withAction

          default <A,​B,​C,​D,​E,​F,​G> R withAction​(@Nullable
                                                                                   ActionHandler7<A,​B,​C,​D,​E,​F,​G> action)

      Returns a copy of `this` immutable component with the specified `action`.
      Parameters:
        `action` - A new action of `ActionType` to register (can be `null`)
      Returns:
        A modified copy of the `this` object
      See Also:
        `ActionHandler7`, `withAction(ActionHandler)`

    - #### withAction

          default <A,​B,​C,​D,​E,​F,​G,​H> R withAction​(@Nullable
                                                                                           ActionHandler8<A,​B,​C,​D,​E,​F,​G,​H> action)

      Returns a copy of `this` immutable component with the specified `action`.
      Parameters:
        `action` - A new action of `ActionType` to register (can be `null`)
      Returns:
        A modified copy of the `this` object
      See Also:
        `ActionHandler8`, `withAction(ActionHandler)`

    - #### withAction

          default <A,​B,​C,​D,​E,​F,​G,​H,​I> R withAction​(@Nullable
                                                                                                   ActionHandler9<A,​B,​C,​D,​E,​F,​G,​H,​I> action)

      Returns a copy of `this` immutable component with the specified `action`.
      Parameters:
        `action` - A new action of `ActionType` to register (can be `null`)
      Returns:
        A modified copy of the `this` object
      See Also:
        `ActionHandler9`, `withAction(ActionHandler)`

    - #### getWidgetListeners

          @Nullable
          java.util.Map<java.lang.String,​java.lang.String> getWidgetListeners()

      Returns the client widget listeners.

    - #### withWidgetListeners

          R withWidgetListeners​(@Nullable
                                java.util.Map<java.lang.String,​? extends java.lang.String> widgetListeners)

      Returns a copy of `this` immutable component with the specified `widgetListeners`.

      Sets or removes an event listener of the peer widget. If there is an event listener associated with the same event, the previous one will be replaced.

      Parameters:
        `widgetListeners` - The client widget listeners
      Returns:
        A modified copy of the `this` object

    - #### withWidgetListener

          default R withWidgetListener​(java.lang.String eventName,
                                       java.lang.String script)

      Returns a copy of `this` immutable component with the specified `eventName` and `script`.

      Sets or removes an event listener of the peer widget. If there is an event listener associated with the same event, the previous one will be replaced.

      Parameters:
        `eventName` - The event name, such as `onClick`
        `script` - The script to handle the event. If null, the event handler is removed.
      Returns:
        A modified copy of the `this` object

    - #### getWidgetOverrides

          @Nullable
          java.util.Map<java.lang.String,​java.lang.String> getWidgetOverrides()

      Returns the mapping of the script and the function definition to override widget's methods and attributes, or null.

    - #### withWidgetOverrides

          R withWidgetOverrides​(@Nullable
                                java.util.Map<java.lang.String,​? extends java.lang.String> widgetOverrides)

      Returns a copy of `this` immutable component with the specified `widgetOverrides`.

      Sets or removes a method or an attribute of the peer widget (at the client). If there is a method or an attribute associated with the same name, the previous one will be replaced.

      If there is no previous method or attribute, the method/attribute will be assigned directly.

      Parameters:
        `widgetOverrides` - The client widget overrides for methods and attributes
      Returns:
        A modified copy of the `this` object

    - #### withWidgetOverride

          default R withWidgetOverride​(java.lang.String name,
                                       java.lang.String script)

      Returns a copy of `this` immutable component with the specified `name` and `script`.

      Sets or removes a method or an attribute of the peer widget (at the client). If there is a method or a attribute associated with the same name, the previous one will be replaced.

      Parameters:
        `name` - The attribute name to override, such as `setValue` and `miles`.
        `script` - the method definition, such as `function (arg) {...}`, or a value, such as `123` and `new Date()`. If not null, this method will be added to the peer widget. If there was a method with the same name, it will be renamed to `$name` so can you call it back.

            .withWidgetOverride("setValue", "function (value) {" +
              "this.$setValue(value); //old method" +
             "}");

        If null, the previous method, if any, will be restored.
      Returns:
        A modified copy of the `this` object

    - #### getClientAttributes

          @Nullable
          java.util.Map<java.lang.String,​java.lang.String> getClientAttributes()

      Returns the client DOM attributes.

    - #### withClientAttributes

          R withClientAttributes​(@Nullable
                                 java.util.Map<java.lang.String,​? extends java.lang.String> clientAttributes)

      Returns a copy of `this` immutable component with the specified `clientAttributes`.

      Sets or removes a DOM attribute of the peer widget (at the client). ZK pass the attributes directly to the DOM attribute generated at the client.

      Parameters:
        `clientAttributes` - The client DOM attributes
      Returns:
        A modified copy of the `this` object

    - #### withClientAttribute

          default R withClientAttribute​(java.lang.String name,
                                        java.lang.String value)

      Returns a copy of `this` immutable component with the specified `name` and `value`.

      Sets or removes a DOM attribute of the peer widget (at the client). ZK pass the attributes directly to the DOM attribute generated at the client.

      Parameters:
        `name` - the attribute name to generate to the DOM element, such as `onload`.
        `value` - the value of the attribute. It could be anything depending on the attribute. If null, the attribute will be removed. Make sure to specify an empty string if you want an attribute with an empty value.
      Returns:
        A modified copy of the `this` object