Property Rendering

If a state (aka., a property) of a component will cause the peer widget to have a different behavior or visual appearance, the state has to be sent to the widget to ensure the consistency.

There are two situations a component has to send the states to the client.

1. Render All Properties When Attached

   A component has to render all properties when it is attached to a page at the first time

2. Dynamic Update a Property

   A component has to send the new value of a property when it is changed dynamically.

---

Notice that this section describes how to synchronize states of a component to the widget. To synchronize states back to a component, refer to the AU Requests section.

Render All Properties When Attached

When ZK is about rendering a new-attached component to the client (by new-attached we mean just attached to a desktop), ComponentCtrl.redraw(Writer) is called to render the component, including the widget's class name, all properties, event listeners and so on.

However, you don't have to implement ComponentCtrl.redraw(Writer) from ground up. AbstractComponent provides a default implementation, so you could override AbstractComponent.renderProperties(ContentRenderer) instead.

renderProperties

Overriding AbstractComponent.renderProperties(ContentRenderer) is straightforward: call back super.renderProperties to render inherited properties, and then call one of the render methods to render the properties of the component.

protected void renderProperties(ContentRenderer renderer)
throws IOException {
 super.renderProperties(renderer);
 render(renderer, "myProp", _myProp);
 //...
}

Notice that the render methods of AbstractComponent will ignore null, empty string, and false automatically. Thus, the if statement in the following example is redundant.

if (value != null && value .length() != 0) //redundant since render will check
    render(renderer, "name", value); //does nothing if null or empty

On the other hand, if you want to render null and an empty string, you shall invoke the render methods of ContentRenderer, such as

render.render("name", value);

redrawChildren

After calling renderProperties, redraw calls AbstractComponent.redrawChildren(Writer) to render the properties of children recursively.

Here is the calling sequence of the default implementation of AbstractComponent.redraw(Writer):

1. renderProperties(new JsContentRenderer());
2. redrawChildren(out);

Render Special Properties

ZK Client Engine supports several special properties to provide extra functionality, such as late evaluation and so on.

z_al

Specifies a map of properties that shall be evaluated after all script files are loaded.

For example,

protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer)
throws java.io.IOException {
  //assume js is the JavaScript code snippet
  renderer.renderDirectly("z_al", "{constraint:function(){\nreturn "+js+";}}");
}

Notice that the value of z_al is a JavaScript map of properties that will be evaluated, after all required JavaScript packages are loaded. Moreover, the value of each entry in the map is a function that shall return the object being assigned with.

In the above example, the function will be invoked after all packages are loaded, and then the returned value, js will be assigned to the constraint property.

z_ea

Specifies the property name whose value must be retrieved from the DOM element with the same UUID.

It is used to create a ZK application that can be crawled by search engines.

Example,

renderer.render("z_ea", "content");

Then, the content property's value will become the inner HTML of the DOM element with the same UUID.

If the content has to decode first (from &lt; to <, see zUtl#decodeXML), prefix the property name with '$'.

renderer.render("z_ea", "$content");

z_pk

Specifies a list of packages separated by comma that shall be loaded before creating widgets.

Example,

renderer.render("z_pk", "com.foo,com.foo.more");

Enforce ZK Update Engine to Redraw a Component

A component can enforce ZK Update Engine to redraw a component by calling Component.invalidate(). Once called, the peer widget will be removed, and a new peer widget will be created to represent the new content. Thus, all modification to the widget at client will be lost if not preserved (or synchronized back) to the server.

Also notice that Component.redraw(Writer) won't be called immediately. Rather, ZK Update Engine will accumulate all updates, and then optimize the number of commands (AU responses) that need to be sent.

Dynamic Update a Property

When the application modifies a property that affects the peer widget, a component has to send the updated value to the peer widget. It is done by calling smartUpdate of AbstractComponent. For example,

public void setValue(String value) {
 if (!_value.equals(value)) {
  _value = value;
  smartUpdate("value", _value);
 }
}

If the peer widget was created in the previous request (i.e., the component was attached to page), the invocation of smartUpdate actually cause the peer widget's setter of the specified properties being called. In the above example, setValue will be called at the client.

On the other hand, if a component is not yet attached to a page, smartUpdate does nothing (since the peer widget doesn't exist). If invalidate was called, smartUpdate does nothing and previous invocation of smartUpdate of the same request are ignored (since the peer widget will be removed and re-created).

Deferred Property Value

Sometimes the value is not ready when smartUpdate is called, and it is better to generate in the rendering phase. For example, encodeURL is better to be called in the rendering phase. To defer the evaluation of a value, you can implement the org.zkoss.zk.ui.util.DeferedValue interface.

public void setSrc(String src) {
 if (!Objects.equals(_src, src)) {
  _src = src;
  smartUpdate("src", new EncodedURL());
 }
}
private class EncodedURL implements DeferedValue {
 public Object getValue() {
  return getDesktop().getExecution().encodeURL(_src);
 }
}

---

Version History

Version	Date	Content