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);
 //...
}

redrawChildren

After calling renderProperties, redraw calls redrawChildren to render the properties of children.

Here is the calling sequence of the default implementation of redraw in HtmlBasedComponent:

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

Enforce ZK Update Engine to Redraw a Component

A component can enforce ZK Update Engine to redraw a component by calling the invalidate method (of the Component interface).

Notice that 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.

Also notice that redraw won't be called immediately. Rather, it is called later, after the AU request has been processed, and right before sending the response to the client.

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