ZK Component Reference/Events/CreateEvent

CreateEvent

• Demonstration: N/A
• Java API: CreateEvent
• JavaScript API: N/A

Employment/Purpose

Used to notify a window that all its children are created and initialized. UiEngine post this event to components that declares the onCreate handler (either as a method or as in instance definition).

Example

N/A

Notes

Use with data binding

When the data binder processed a collection of data in, say, a grid or a listbox, it will detach the original one, and then clone it to represent each item of the data. For example,

<listbox model="@{person.interests}">
	<listitem self="@{each=obj}" value="@{obj}" onCreate="foo()"/>
</listbox>

where the execution sequence is as follows.

1. ZK Loader creates a listbox and a listitem, and posts onCreate to the listitem (since it has a listener).
2. The data binder processes all annotations, after all components are created.
   1. When handling each, the data binder detaches the listitem, invokes Component.clone() to make a clone for each item (person.interests), and attach the clone to the listbox.
3. The listitem created by ZK Loader receives onCreate.

The detail behavior of step 3 is a bit different since 5.0.4. We will discuss it more detailed in the following sections.

5.0.3 and earlier

With 5.0.3 and earlier, only the original listitem (the listitem used as template to be cloned) will receive onCreate. Thus, whatever change the listener made won't affect the cloned listitems.

In summary, when using data binding with 5.0.3 or earlier, don't use onCreate.

5.0.4

Since 5.0.4, the data binder will fire onCreate to each cloned component, so it is safe to use onCreate with the data binder.

However, there is one more thing to be noticed: how the event listener is cloned when a component is cloned. By default, the new component will share the same listener with the original component. Sometimes, it might not be correct (for example, the listener might be an inner class that assumes this to be the original component), the event listener shall implement ComponentCloneListener to clone the listener by itself. For example,

public FooCreateListener implements EventListener, ComponentCloneListener {
  private Listitem _item;
  public FooListener(Listitem item) {
    _item = item;
  }
  public Object willClone(Component comp) {
    return new FooListener((Listitem)comp);
  }
  public void onEvent(Event evt) {
   //handle _item
  }
}

Instead of implementing ComponentCloneListener, using <javadoc method="getTarget()">org.zkoss.zk.ui.event.Event</java> could be easier way to make a listener safe to clone.

public FooCreateListener implements EventListener, ComponentCloneListener {
  public void onEvent(Event evt) {
    Listitem item = (Listitem)evt.getTarget();
    //then, handle item
  }
}

Supported events

Name	Event Type
None	None

Supported Children

*NONE

Use cases

Version	Description	Example Location

Version History

Version	Date	Content