Package org.zkoss.zk.ui.util

Class Composition

  • All Implemented Interfaces:
    Initiator, InitiatorExt
    public class Composition
extends java.lang.Object
implements Initiator, InitiatorExt

    Composition manager that compose the given components into a whole page per the "insert" components and "define" components annotations. The "define" components will attach itself on to the "insert" component with the same annotated joinId. That is, the "insert" component is the parent component of the "define" components with the same annotated joinId. Note that "insert" components can NOT have duplicate joinId in a page while "define" components can because you can have multiple child components but you cannot have multiple parent components. Also note that a "define" components must be a root component of the page.

    This Composition manager is useful when you need to do layout injection or you want to design a common page template across multiple pages.

    • You first design a template with "insert" components telling where the insert points are. Each insert component has to be given a distinguish joinId in a page(e.g. <window self="@{insert(content)}"/> here the "content" is the joinId).
    • Then in the real page, you have root "define" components telling which "define" components are to be attach onto the "insert" component with the same joinId (e.g. <label self="@{define(content)}"; here the "content" is the joinId).
    • This Composition class is designed as a page Initiator and a InitiatorExt, so you have to specify in the real page as following to use it. 
       
 <?init class="org.zkoss.zk.ui.util.Composition" [arg0="TEMPLATE1"[, arg1="TEMPLATE2"]...]?>
 ...
      Where the arg0 ~ argx you can give zul template uri. This implementation use Excecutions.createComponents() to create them and then do the real composition in the InitiatorExt.doAfterCompose(Page, Component[]).
    • If more than one "define" components have the same joinId, they are attached onto the "insert" component in the sequence of the definition.
    • If a "define" component cannot find the corresponding "insert" component, it will be simply detached from the page.
    • Also you can prepare a parent component and pass it in via Execution.getCurrent().setAttribute(Composition.PARENT, parent) then this implementation will attach finally composed root components as the children of the provided parent.
    • If you did not provide the parent component, the finally composed root components are attached directly to the current page.
    Since:
    3.5.2
    Author:
    henrichen

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String PARENT  

    • Constructor Summary

      Constructors 
      Constructor Description
      Composition()  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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<java.lang.String,​java.lang.Object> 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