ZK Developer's Reference/UI Composing/Shadow for MVC

Introduction

Since ZK 8.0.0, we have introduced shadow elements like a boilerplate code to help application developers compose html layouts with dynamic data. It is inspired from Shadow DOM to enable better composition of ZK components. For more details, please check out our Official ZK MVVM Book. Shadow elements cannot only be used with MVVM binding but also with MVC pattern; however, there are some differences. We will discuss this more in the following sections.

In MVC pattern, developers can declare shadow tags in zul files, but 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 favor MVC, that is, ShadowTemplate and CollectionTemplate.

They are NOT like the typical shadow elements defined in zul but components you can only create 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 HtmlShadowElement.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(host) 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

CollectionTemplate is similar to ShadowTemplate. The difference is that developers can assign ListModel and CollectionTemplateResolver for iterative rendering.

Example

The basic usage is simple. Here we demonstrate by using the previous sample code.

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

The each in line 6, 7, 8 represents each item in ListModel, and in DemoComposer.java

@Wire
Div host1;
ListModel model = new ListModelList(Arrays.asList(new String[]{"1", "2", "3"}));

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

Developers have to prepare a ListModel and assign to the CollectionTemplate instance; then, they will see the template is created multiple times. Similarly, in cases where either template or model is changed, apply(host) must be triggered for the effect to take place. The benefit of using CollectionTemplate is that every time the model's content changes, the layout will change as well, no matter if autodrop is true or false.

CollectionTemplateResolver

More advanced usage is to assign CollectionTemplateResolver to resolve template by evaluating the variable reference from model in runtime.

<zk>
	<div id="root" apply="DemoComposer">
		<div id="host1"></div>
	
		<template name="male">
			<div>
				<label>I'm male, my name is ${each.name}</label>
			</div>
		</template>
		<template name="female">
			<div>
				<label>I'm female, my name is ${each.name}</label>
			</div>
		</template>
	</div>
</zk>

The each in line 7, 12 represents each item in ListModel, and in DemoComposer.java

@Wire
Div host1;
ListModelList<Person> model = new ListModelList<Person>(new ArrayList<Person>() {{
	add(new Person(true));
	add(new Person(false));
	add(new Person(false));
	add(new Person(true));
}});

public void doAfterCompose(Component comp) throws Exception {
	super.doAfterCompose(comp);
	CollectionTemplate ct = new CollectionTemplate(true); //autodrop = true
	ct.setModel(model);
	ct.setTemplateResolver(new MyCollectionTemplateResolver<Person>());
	ct.apply(host1);
}

public class MyCollectionTemplateResolver<E extends Person> implements CollectionTemplateResolver<E> {
	public Template resolve(E o) {
		if (o.getGender())
			return root.getTemplate("male");
		else
			return root.getTemplate("female");
	}
}

public class Person {
	String name = "old name";
	boolean isMale = true;
	.... getter and setter
}

In this example, we assign an CollectionTemplateResolver instead of template name or URI, and you will see template "male" is rendered when the gender of Person variable is male. That means, CollectionTemplate provides not only setTemplate and setTemplateURI but also supports determining template dynamically by giving CollectionTemplateResolver like line 14, so the template will be resolved by evaluating the variable reference from model in runtime.

---

Note: ShadowTemplate doesn't support set template and template URI at the same time; one of them should be null or empty string before setting another. CollectionTemplate will only consider the last call to either setTemplate, setTemplateURI or setTemplateResolver.

Comparison

Although the behavior between ShadowTemplate and Macro component looks similar, there are some differences.

	ShadowTemplate	Macro Component
change host/parent	if autodrop is true, the rendered components will change parent; otherwise, they will still stick with the same parent(or host).	no matter it is inline or not, the rendered components will change parent.
change template/uri	if autodrop is true, the rendered components will be detached; otherwise, they will still stick with the same parent(or host).	no matter it is inline or not, the rendered components will be detached.

In short, while using Macro component, we would have to instantiate more than one to achieve this goal, ShadowTemplate has more flexibility for templating; developers can render anywhere without losing those rendered components with only one ShadowTemplate instance. CollectionTemplate, too, can render template iteratively with ListModel, a task impossible for Macro component.

Version History

Version	Date	Content