org.zkoss.zk.ui.util
Class GenericComposer

java.lang.Object
  org.zkoss.zk.ui.event.GenericEventListener
      org.zkoss.zk.ui.util.GenericComposer

All Implemented Interfaces:

java.io.Serializable, NamespaceActivationListener, EventListener, Composer, ComposerExt

Direct Known Subclasses:

GenericAutowireComposer, VariableComposer

public abstract class GenericComposer
extends GenericEventListener
implements Composer, ComposerExt, NamespaceActivationListener, java.io.Serializable

An abstract composer that you can extend and write intuitive onXxx event handler methods; this class will registers onXxx events to the supervised component automatically.

The following is an example. The onOK and onCancel event listener is registered into the target main window automatically.

 <zscript><!-- both OK in zscript or a compiled Java class -->
 public class MyComposer extends GenericComposer {
    public void onOK() {
        //doOK!
        //...
    }
    public void onCancel() {
        //doCancel
        //...
    } 
 }
 </zscript>

 <window id="main" apply="MyComposer">
     ...
 </window>
 

since 3.6.1, this composer would be assigned as a variable of the given component per the naming convention composed of the component id and composer Class name. e.g. If the applied component id is "xwin" and this composer class is org.zkoss.MyComposer, then the variable name would be "xwin$MyComposer". You can reference this composer with Component.getVariable(java.lang.String, boolean) or via EL as ${xwin$MyComposer} of via annotate data binder as @{xwin$MyComposer}, etc. If this composer is the first composer applied to the component, a shorter variable name composed of the component id and a String "composer" would be also available for use. Per the above example, you can also reference this composer with the name "xwin$composer"

Since 3.6.2, this composer becomes serializable, so it is better to declare members to be wired as transient, since it will re-write automatically after the session has been activated.

Since:

3.0.1

Author:

robbiecheng

See Also:

Serialized Form

Constructor Summary

GenericComposer()

Method Summary

void	didActivate(Namespace ns) Called when a namespace has activated this object back.
void	doAfterCompose(Component comp) Registers onXxx events to the supervised component; a subclass that override this method should remember to call super.doAfterCompose(comp) or it will not work.
ComponentInfo	doBeforeCompose(Page page, Component parent, ComponentInfo compInfo) Invokes before composing a component.
void	doBeforeComposeChildren(Component comp) Invokes after the component is instantiated and initialized, but before composing any child.
boolean	doCatch(java.lang.Throwable ex) Called when an exception occurs when composing the component.
void	doFinally() Called after the component has been composed completely.
void	willPassivate(Namespace ns) Called when a namespace is going to passivate this object.

Methods inherited from class org.zkoss.zk.ui.event.GenericEventListener

bindComponent, getController, onEvent

Methods inherited from class java.lang.Object

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

Constructor Detail

GenericComposer

public GenericComposer()

Method Detail

doAfterCompose

public void doAfterCompose(Component comp)
                    throws java.lang.Exception

Registers onXxx events to the supervised component; a subclass that override this method should remember to call super.doAfterCompose(comp) or it will not work.

Specified by:

doAfterCompose in interface Composer

Parameters:

comp - the component has been composed

Throws:

java.lang.Exception

doBeforeCompose

public ComponentInfo doBeforeCompose(Page page,
                                     Component parent,
                                     ComponentInfo compInfo)

Description copied from interface: ComposerExt

Invokes before composing a component. If you want to manipulate the specified component info, you can use ComponentInfo.duplicate() to make a copy and then modify it such that it won't affect the default behavior.

Specified by:

doBeforeCompose in interface ComposerExt

Parameters:

page - the page for composing this component.

parent - the parent component, or null if it is the root component.

compInfo - the component info used to instantiate the component.

Returns:

the component info used to instantiate the component. In most case, it shall return compInfo. If null is returned, the component won't be instantiated. In other words, it is ignored.

doBeforeComposeChildren

public void doBeforeComposeChildren(Component comp)
                             throws java.lang.Exception

Description copied from interface: ComposerExt

Invokes after the component is instantiated and initialized, but before composing any child.

Specified by:

doBeforeComposeChildren in interface ComposerExt

Parameters:

comp - the component being composed

Throws:

java.lang.Exception

doCatch

public boolean doCatch(java.lang.Throwable ex)
                throws java.lang.Exception

Description copied from interface: ComposerExt

Called when an exception occurs when composing the component.

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.

Specified by:

doCatch in interface ComposerExt

Parameters:

ex - the exception being thrown

Returns:

whether to ignore the exception. If false is returned, the exception will be re-thrown. Note: once a composer's doCatch returns true, the exception will be ignored and it means doCatch of the following composers won't be called.

Throws:

java.lang.Exception

doFinally

public void doFinally()
               throws java.lang.Exception

Description copied from interface: ComposerExt

Called after the component has been composed completely. It is the last step of the composing.

Note: it is always called even if ComposerExt.doCatch(java.lang.Throwable), ComposerExt.doBeforeComposeChildren(org.zkoss.zk.ui.Component) or Composer.doAfterCompose(org.zkoss.zk.ui.Component) is not called (due to exceptions).

Note: it is called after the onCreate event is posted, but before the onCreate and any other events are handled.

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

Specified by:

doFinally in interface ComposerExt

Throws:

java.lang.Exception

willPassivate

public void willPassivate(Namespace ns)

Called when a namespace is going to passivate this object. Default: does nothing.

Specified by:

willPassivate in interface NamespaceActivationListener

didActivate

public void didActivate(Namespace ns)

Called when a namespace has activated this object back. Default: invokes doAfterCompose(org.zkoss.zk.ui.Component).

Specified by:

didActivate in interface NamespaceActivationListener

Since:

3.6.2