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>, IAvatar, IAvatargroup, IBadge<I>, IBandbox, IBandpopup<I>, IBarcode, IBarcodescanner, IBiglistbox, IBorderlayout, IBreadcrumb, IBreadcrumbitem, IButton, IButtonBase<I>, ICalendar, ICamera, ICaption<I>, ICardlayout<I>, ICarousel, ICarouselitem<I>, ICascader, ICell<I>, ICenter<I>, ICheckbox, ICheckboxBase<I>, IChildrenOfInputgroup<I>, IChildrenOfMenupopup<I>, IChildrenOfNavbar<I>, IChildrenOfPanel<I>, IChildrenOfTab<I>, IChip, IChosenbox, ICoachmark<I>, ICodeeditor, IColorbox, IColumn<I>, IColumnchildren<I>, IColumnlayout, IColumns, ICombobox, ICombobutton, IComboitem, IConfirmpopup, ICropper, IDatebox, IDaterangebox, 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:

  • Method Details

    • getId

      default 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(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

      String getWidgetClass()
      Returns the client widget class which belongs to this component.

    • withWidgetClass

      R withWidgetClass(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 List<ActionHandler> getActions()
      Returns all the ActionHandlers 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:

    • withActions

      R withActions(@Nullable Iterable<? extends ActionHandler> actions)
      Returns a copy of this immutable component with the specified actions.
      Parameters:
      actions - The multiple actions to register with different ActionTypes
      Returns:
      A modified copy of this object
      See Also:

    • 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 String getMold()
      Returns the mold used to render this component.

      Default: "default"

    • withMold

      R withMold(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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • getWidgetListeners

      @Nullable Map<String,String> getWidgetListeners()
      Returns the client widget listeners.

    • withWidgetListeners

      R withWidgetListeners(@Nullable Map<String,? extends 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(String eventName, 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 Map<String,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 Map<String,? extends 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(String name, 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 Map<String,String> getClientAttributes()
      Returns the client DOM attributes.

    • withClientAttributes

      R withClientAttributes(@Nullable Map<String,? extends 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(String name, 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