org.zkoss.zkplus.databind
Class AnnotateDataBinderInit

java.lang.Object
  org.zkoss.zkplus.databind.AnnotateDataBinderInit

All Implemented Interfaces:

Initiator, InitiatorExt

public class AnnotateDataBinderInit
extends java.lang.Object
implements Initiator, InitiatorExt

This initiator class do following things:

1. New an AnnotateDataBinder instance.
2. Set the AnnotateDataBinder instance as a custom attribute with the name as specified in arg2 (default to "binder") and store it in the component as specified in arg0 "component-path".(if arg0 is not specified, use Page instead.)
3. call DataBinder.loadAll() in to doAfterCompose(Page, Component[]) and initiate all UI components from the associated data bean.

Put the init PI as follows:

 <?init class="org.zkoss.zkplus.databind.AnnotateDataBinderInit" 
        [root="component|component-path"] 
  [loadDefault="true|false"]
  [name="binder's name"]
  [loadOnSave="true|false"] ?>
 

Where the root attribute is the component itself (via EL expression) or the component path that specifies the component the AnnotateDataBinder covers. You can use absolute path that starts with "//" (search from Desktop) or "/" (search from Page); or you can use relative path(supported since ZK 3.0.8) that starts with "./" or "../" (relative to the Id Space of the root component). If the root attribute is not specified or set to string "page", the AnnotateDataBinder will default to cover the whole page.

Where the loadDefault attribute is used to decide whether to load default binding configuration defined in lang-addon.xml. If the loadDefault attribute is not specified it is default to true.

(since 3.6.2) Where the name attribute is used to specify the created DataBinder's name (default to "binder") which you can access it via EL or component.getAttribute(name) later.

(since 5.0.5) Where the loadOnSave attribute(default to true) is used to specify whether DataBinder shall automatically "load" associated binding value back into UI component after doing a "save" operation to the binding bean.

For application design to run ZK prior to 3.6.2, it can use arg0 instead of root, and arg1 instead of loadDefault.

Note that since 5.0, the created DataBinder is stored in component scope of the root component rather than in the IdSpace scope of the root component. If that is important to you, you can specify compatible library property in WEB-INF/zk.xml to true to make it work as it was prior version 5; i.e. store the created DataBinder in IdSpace scope of the root component.

        <library-property>
                <name>org.zkoss.zkplus.databind.AnnotateDataBinderInit.compatible</name>
                <value>true</value>
        </library-property>
 

Author:

Henri Chen

See Also:

AnnotateDataBinder

Field Summary

protected AnnotateDataBinder

_binder The AnnotateDataBinder created in doAfterCompose()

Constructor Summary

AnnotateDataBinderInit()

Method Summary

void	doAfterCompose(Page page, Component[] comps) Called after all components are created (a.k.a., composed), and before any event is processed.
boolean	doCatch(java.lang.Throwable ex) Called when an exception occurs during the evaluation of the page.
void	doFinally() Do the cleanup after the page has been evaluated.
void	doInit(Page page, java.util.Map args) Does the initializes before the page is evaluated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_binder

protected AnnotateDataBinder _binder

The AnnotateDataBinder created in doAfterCompose()

Constructor Detail

AnnotateDataBinderInit

public AnnotateDataBinderInit()

Method Detail

doCatch

public boolean doCatch(java.lang.Throwable ex)

Description copied from interface: InitiatorExt

Called when an exception occurs during the evaluation of the page.

If you don't want to handle the exception, simply returns false. boolean doCatch(Throwable ex) {return false;}

An exception thrown in this method is simply logged. It has no effect on the execution. If you want to ignore the exception, just return true.

Notice: this method won't be called if the exception occurs in Initiator.doInit(org.zkoss.zk.ui.Page, java.util.Map).

Specified by:

doCatch in interface InitiatorExt

Parameters:

ex - the exception being thrown

Returns:

whether to ignore the exception. If false is returned, the exception will be re-thrown. Note: once an initiator's doCatch returns true, the exception will be ignored and it means doCatch of the following initiators won't be called. Prior to ZK 3.0.0, void is returned and it means always re-thrown

doFinally

public void doFinally()

Description copied from interface: InitiatorExt

Do the cleanup after the page has been evaluated. It won't be called if Initiator.doInit(org.zkoss.zk.ui.Page, java.util.Map) throws an exception. However,it is always called no matter whether InitiatorExt.doCatch(java.lang.Throwable) is called.

An exception thrown in this method is simply logged. It has no effect on the execution.

Specified by:

doFinally in interface InitiatorExt

doInit

public void doInit(Page page,
                   java.util.Map args)

Description copied from interface: Initiator

Does the initializes before the page is evaluated.

Note: when it is called, Page.getDesktop(), Page.getId() and Page.getTitle() all return null, since the page is not initialized yet. To get the current desktop, you have to use Execution.getDesktop() (from Executions.getCurrent()) instead. On the other hand, you can set the page's ID, title or style in this method (to override the declarations in the page definition) by Page.setId(java.lang.String), Page.setTitle(java.lang.String) and Page.setStyle(java.lang.String). In additions, Page.getRequestPath() and Page.getAttribute(java.lang.String, int) are all available.

Specified by:

doInit in interface Initiator

Parameters:

page - the page being evaluated

args - a map of arguments. Prior to 3.6.2, it is an array. To upgrade, use args.get("arg0") instead of args[0], args.get("arg1") instead of args[1] and so on. Of course, it is better to have a more meaningful name for each argument. If no argument is specified, args is an empty map (never null).

doAfterCompose

public void doAfterCompose(Page page,
                           Component[] comps)
                    throws java.lang.Exception

Description copied from interface: InitiatorExt

Called after all components are created (a.k.a., composed), and before any event is processed.

It won't be called if an un-caught exception occurs when creating components.

Specified by:

doAfterCompose in interface InitiatorExt

Parameters:

page - the page that new components are attached to. It is the same as Initiator.doInit(org.zkoss.zk.ui.Page, java.util.Map)'s page argument.

comps - the root components being created (never null, but the length might be zero). Note: It is not necessary the same as Page.getRoots(), since this method might be called thru Executions.createComponents(java.lang.String, org.zkoss.zk.ui.Component, java.util.Map).

Throws:

java.lang.Exception