ZK Developer's Reference/Stateless Components/Building Stateless UI

Setting up

To set up stateless components in a ZK 10 application, you need to include the stateless components module and define a Dispatcher Richlet Filter in your WEB-INF/web.xml file.

Including Required Jar

dependencies {
    implementation "org.zkoss.zk:stateless:${zkVersion}"
    ...
}

Dispatcher Richlet Filter

<filter>
    <filter-name>DispatcherRichletFilter</filter-name>
    <filter-class>org.zkoss.stateless.ui.http.DispatcherRichletFilter</filter-class>
    <init-param>
        <param-name>basePackages</param-name>
        <param-value><!-- your base packages --></param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>DispatcherRichletFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Example Application

We will use the simple shopping cart application as an example to introduce basic features of stateless components:

Building UI with Richlet

Building user interfaces (UI) with stateless components requires creating a StatelessRichlet and mapping a URL to that richlet.

URL Mapping

We use @RichletMapping to compose a URL. When users visit that URL, ZK will invoke the corresponding method.

For example below, the index() URL will be <protocal>:// <host name: port> /shoppingCart.

    @RichletMapping("/shoppingCart")
    public class DemoRichlet implements StatelessRichlet {
        @RichletMapping("")
        public List<IComponent> index() {
            //return ...
        }
    }

Class-Level Mapping

At this level, @RichletMapping defines the base path for all methods in a StatelessRichlet. For example, assigning @RichletMapping("/shoppingCart") to the DemoRichlet class sets a foundational path for all UI components it manages.

Method-Level Mapping

Within the StatelessRichlet, each method can specify further URL mapping. By applying @RichletMapping("") to a method, it effectively inherits the class-level path. Hence, the shoppingCart() method is accessible via the URL <protocol>://<hostname>:<port>/shoppingCart.

Composing the UI with Stateless Components

Before ZK 10, ZK components are stateful, meaning that the server holds the state. Starting from ZK 10, we provide a set of stateless components as Immutable objects. Immutable objects are constructed once and can not be changed after they are constructed. After Immutable objects are rendered, they will be destroyed. Since the component state will not be saved on the server, they consume less memory.

UI Composing

With ZK 10 stateless components, you will no longer write a zul file. You will be composing your view using the stateless components and their APIs in Java.

• ZK component having a prefix letter "I" represents an immutable component.
• We offer of() API for commonly used properties.
• withSclass() means the setter of sclass.

    // ZK 10
    IButton.of("add items")
           .withSclass("add-items");

    // ZK 9
    // equivalent idea as above.
    Button button = new Button("add items");
    button.setSclass("add-items");

Event Wiring

To wire an event listener, you need to declare the ActionHandler method, with an annotation @Action.

• The method should be public.
• The parameter of @Action should be one of event types.
• Wire the action handler with the target component by withAction(ActionHandler action).

    // ActionHandler method
    @Action(type = Events.ON_CLICK) // Wiring event
    public void addItem() {
        ...
    }

    public IComponent demo() {
         return IButton.of("add items").withSclass("add-items")
                .withAction(this::addItem);
    }

Obtain Widget State

Since a server no longer holds a component's state, we provide @ActionVariable to access component attributes and state sent from the client.

• @ActionVariable(targetId = ActionTarget.SELF, field = "id") retrieves the value from the field of a component with the targetId on the client.
• ActionTarget.SELF means it targets the component associates to the event itself.

    @Action(type = Events.ON_CLICK)
    public void addItem(@ActionVariable(targetId = ActionTarget.SELF, field = "id") String orderId) {
    }

Update Widget State

To update the widget state, we provide several APIs in UiAgent. The state will be updated to the client immediately.

• The following example will add the specified child component as the last child to the locator.

    @Action(type = Events.ON_CLICK)
    public void addItem(@ActionVariable(targetId = SELF, field = "id") String orderId) {
        UiAgent.getCurrent().appendChild(Locator.ofId("shoppingBagRows"), addShoppingBagItem(parseUuid(orderId)));
    }

Example Application

You can download the shopping cart demo project.