Shadow for MVC

Introduction

Since ZK 8.0.0, we introduce shadow elements like a boilerplate code to help application developers to compose the html layout with some dynamic data. It is inspired from Shadow DOM to enable better composition of ZK components. For more detail, please check out our Official ZK MVVM Book. Shadow elements can not only be used with MVVM binding but also MVC pattern, but there are some differences. We will give more discussion in the following sections.

In MVC pattern, developers can declare shadow tags in zul files while the behavior is very different without MVVM annotation. For Example,

<apply template="any" />
<template name="any">
    ...
</template>

The shadow element apply will not exist once the output is rendered to client, so developers can't dynamically change the template value. For this purpose, we provide two kinds of Java class for those who have favor of MVC, that is, ShadowTemplate and CollectionTemplate.

They are NOT like normal shadow elements defined in zul but you can only create instances in Java code.

Use ShadowTemplate

ShadowTemplate is a utility class to let developers to apply shadow elements in Java class. It has the similar behavior with Apply, for example, developers can specify the template or pass parameters. The difference is that developers must designate a boolean value, called autodrop, to indicate whether to drop those rendered children or not. If true, every time user changed template or detach from the original host, ShadowTemplate will Apply.recreate() or removed the children, otherwise, rendered children will be remained. After instantiating ShadowTemplate instance, developers can trigger ShadowTemplate.apply(Component) to compose the specified template with shadow host passed as parameter. Note that, the passed host should be the same one if autodrop is true, or pass null to detach the original host first.

Example

Assume we have a zul file like this:

<zk>
	<div apply="DemoComposer">
		<div id="host1"></div>
	</div>
	<template name="labels">
		<label value="zul label"/>
		<x:label>xhtml label</x:label>
		<n:span>native span</n:span>
	</template>
</zk>

and in DemoComposer.java

@Wire
Div host1;

public void doAfterCompose(Component comp) throws Exception {
	super.doAfterCompose(comp);
	ShadowTemplate st = new ShadowTemplate(true); //autodrop = true
	st.setTemplate("labels");
	st.apply(host1);
}

In line 6, we instantiate a new ShadowTemplate with autodrop equal to true.

In line 7, assign the template name to st.

In line 8, call apply method and shadow host is Div host1.

Then, we can see template "labels" is rendered and the created component are attached to host1.

If we have a button to change the template,

	@Listen("onClick = #btn")
	public void clickBtn() {
		st.setTemplate("othertemplate");
		st.apply(st.getShadowHost());
	}

Those components rendered before will be detached first, and attach the new ones, note that, developers have to call apply method again. If developers want to apply to other shadow host, please apply null first and then apply again like this:

st.apply(null);
st.apply(otherHost);

And the rendered components will also be detached.

Another case is autodrop equal to false, and then neither change template nor apply to other host(yes, you can apply different host whatever you want) won't cause rendered components being detached.

Use CollectionTemplate

First, you have to decide which component to extend from. Div is a common choice as it is a simple component. However, here our example extends from Row, so it can be used under Rows, which the regular macros cannot.

Second, you have to implement a template (in a ZUML document) to define what child components the composite component has. Then, you have to implement a Java class to put them together.

Implement a Template

The implementation of a template is straightforward. There is nothing special to handle. Since it is rendered by Execution.createComponents(String, Component, Map), you could pass whatever data you prefer to it (through the arg argument).

Suppose we have a template as follows, and it is placed at /WEB-INF/composite/username.zul.

<zk>
  Usename: <textbox id="mc_who"/>
</zk>

Implement a Java Class

To implement a Java class we shall:

1. Extend from the component class you want.
2. (Optional) Implement IdSpace to make it an ID space owner.
3. Render the template in the constructor by the use of Executions.createComponents(String, Component, Map) or others.
4. (Optional) Wire variables, components and event listeners after rendering with the use of Selectors.wireVariables(Component, Object, List) (wiring variables), Selectors.wireComponents(Component, Object, boolean) (wiring components) and Selectors.wireEventListeners(Component, Object) (wiring event listener).

For example,

package foo;

import org.zkoss.zk.ui.IdSpace;
import org.zkoss.zk.ui.select.Selectors;
import org.zkoss.zul.Row;
import org.zkoss.zul.Textbox;

public class Username extends Row implements IdSpace {
    @Wire
    private Textbox mc_who; //will be wired when Components.wireVariables is called

    public Username() {
        //1. Render the template
        Executions.createComponents("/WEB-INF/composite/username.zul", this, null);

        //2. Wire variables, components and event listeners (optional)
        Selectors.wireVariables(this, this, null);
        Selectors.wireComponents(this, this, false);
        Selectors.wireEventListeners(this, this);
    }
    public String getWho() {
        return mc_who.getValue();
    }
    public void setWho(String who) {
        mc_who.setValue(who);
    }
    //public void onOK() {..} //Add event listeners if required, and wired by Components.addForwards
}

After Executions.createComponents(String, Component, Map) is called, all components specified in the template will be instantiated and become the child component of the composite component (Row). Notice that the URI must match the location of the template correctly.

Depending on the implementation you want, you could wire the data members (mc_who) by calling Selectors.wireComponents(Component, Object, boolean). This method will search all data members and setter methods and wire the component with the same ID. Similarly, Selectors.wireEventListeners(Component, Object) is used to wire event listeners.

For more information, please refer to the the Wire Components section and Wire Event the Listeners section sections.

---

Notice that there is a utility called ZK Composite. With the help of ZK Composite, components are created and wired automatically based on the Java annoataions you provide. In other words, Step 3 and 4 are done automatically. For more information, please refer to the Define Components with Java Annotations section.

Wire Spring-managed Beans

Selectors.wireVariables(Component, Object, List) will wire variables that can be resolved by the registered variable resolver. In additions to the variable-resolver directive, you can create any variable resolver manually and pass it as the third argument. Selectors.newVariableResolvers(Class, Class) provides a convenient way to instantiate variable resolvers. For example, let us say we'd like to wire Spring-manage beans, then we can do as follows.

@VariableResolver(org.zkoss.zkplus.spring.DelegatingVariableResolver)
public class Username extends Row implements IdSpace {
    @WireVariable
    private User user;

    public Username() {
        Executions.createComponents("/WEB-INF/composite/username.zul", this, null);

        Selectors.wireVariables(this, this,
            Selectors.newVariableResolvers(getClass(), Row.class));
        Selectors.wireComponents(this, this, false);
        Selectors.wireEventListeners(this, this);
    }
...

Selectors.newVariableResolvers(Class, Class) will look for the @VariableResolver annotation and instantiate it automatically. As shown, we annotate DelegatingVariableResolver to resolve Spring managed bean.

For more information, please refer to the Wire Variables section.

ID Space

Unless you extend a component that is an ID space owner (such as Window), all child components specified in the template will be in the same ID space as its parent. It might be convenient at the first glance. However, it will cause the ID conflict if we have multiple instances of the same composite component. Thus, it is generally suggested to make the composite component as a space owner

It can be done easily by implementing an extra interface IdSpace. No other method needs to be implemented.

public class Username extends Row implements IdSpace {
...

Of course, if you prefer not to have an additional ID space, you don't need to implement an IdSpace.

Use Composite Component

Like macros and any other primitive components, you have to declare a composite component before using it. This can be done by using component directives. Then, we could use it the same way (they are actually primitive components). For example,

<?component name="username" extends="row" class="foo.Username"?>

<grid>
    <rows>
      <username who="Joe"/>
      <username who="Hellen"/>
    </rows>
</grid>

Define Composite Components as Standard Components

If a composite component is used in multiple pages, it is better to define it in the application level, such that it can be accessed in any page without any component directives.

There are basic two approaches to define a component in the application level:

1. Define it in a XML file which is called language addon.
2. Define it with Java annoataions.

Define Components in a Language Addon

A language addon is a XML file providing additional component definitions or customizing the standard components. For example, you can define the username component described in the previous section as follows.

<language-addon>
    <addon-name>myapp</addon-name>
    <component>
        <component-name>username</component-name>
        <extends>rows</extends>
        <component-class>foo.Username</component-class>
    </component>
</language-addon>

For more information, please refer to Customization: Component Properties.

Define Components with Java Annotations

Instead of maintaining the definitions in the language addon as described above, you can define the component with Java annotation with a utility called ZK Composite. For example,

@Composite(name="username", macroURI="/WEB-INF/partial/username.zul")
public class Username extends Rows implements IdSpace {
    @Wire
    private Textbox mc_who; //will be wired when Components.wireVariables is called
 
    //Note: no need to create components and wire variables/components

    public String getWho() {
        return mc_who.getValue();
    }
    public void setWho(String who) {
        mc_who.setValue(who);
    }
}

This approach is suggested if you have to develop several composite components. As shown, it is more convenient since you don't have to maintain a separated XML file (the language addon). Furthermore, it will create the components and wire them automatically based on the annotations.

Notice that it requires additional JAR files, please refer to Small Talks: Define Composite Component using Java Annotation in ZK6 for the details.

Version History

Version	Date	Content