Package org.zkoss.zk.ui

## Class HtmlMacroComponent

- java.lang.Object
- - org.zkoss.zk.ui.AbstractComponent
  - - org.zkoss.zk.ui.HtmlBasedComponent
    - - org.zkoss.zk.ui.HtmlMacroComponent

- All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Cloneable`, `Component`, `AfterCompose`, `DynamicPropertied`, `Macro`, `Scope`, `IdSpace`, `ComponentCtrl`

      public class HtmlMacroComponent
      extends HtmlBasedComponent
      implements Macro

  The implementation of a macro component for HTML-based clients.

  Generally, a macro component is created automatically by ZK loader. If a developer wants to create it manually, it has to instantiate from the correct class, and then invoke `afterCompose()`.

  To do additional application-specific tasks, you could override `compose()`. Both `afterCompose()` and `recreate()` depends on `compose()`.

  By default, `compose()` will wire members by use of `Selectors`. In other words, it will wire annotated members the same way as `SelectorComposer` does.

  If you prefer to wire the members based on the name convention as `GenericForwardComposer` does (i.e., backward compatible with ZK 5), you could specify a library property called `org.zkoss.zk.ui.macro.autowire.convention` to true in WEB-INF/zk.xml as follows.

              <library-property>
                      <name>org.zkoss.zk.ui.macro.autowire.convention</name>
                      <value>true</value>
              </library-property>

  If you prefer not to wire at all (neither by-selector nor by-convention), you could specify a library property called `org.zkoss.zk.ui.macro.autowire.disabled` to true in WEB-INF/zk.xml as follows..

              <library-property>
                      <name>org.zkoss.zk.ui.macro.autowire.disabled</name>
                      <value>true</value>
              </library-property>

  Author:
    tomyeh
  See Also:
    Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.zkoss.zk.ui.HtmlBasedComponent

      `HtmlBasedComponent.ExtraCtrl`

    - ### Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

      `AbstractComponent.Children, AbstractComponent.ForwardInfo, AbstractComponent.TargetInfo`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.util.List<VariableResolver>` | `_resolvers` | A list of resolvers (never null).

    - ### Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

      `_zclass`

    - ### Fields inherited from interface org.zkoss.zk.ui.Component

      `APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE`

    - ### Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl

      `AFTER_CHILD_ADDED, AFTER_CHILD_REMOVED, AFTER_CLONED, AFTER_PAGE_ATTACHED, AFTER_PAGE_DETACHED, AFTER_PARENT_CHANGED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `HtmlMacroComponent()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `afterCompose()` | Creates the child components after apply dynamic properties `setDynamicProperty(java.lang.String, java.lang.Object)`.
    `java.lang.Object` | `clone()` | Clones the component.
    `protected void` | `compose()` | Composes the macro component.
    `java.util.Map<java.lang.String,​java.lang.Object>` | `getDynamicProperties()` | Returns all available dynamic properties.
    `java.lang.Object` | `getDynamicProperty​(java.lang.String name)` | Returns the property value of the specified name.
    `java.lang.String` | `getEnclosingTag()` | Returns the name of the enclosing tag for this macro component.
    `java.lang.String` | `getMacroURI()` | Returns the macro URI.
    `java.lang.String` | `getWidgetClass()` | Returns the component class (a.k.a., widget type), "zk.Macro".
    `boolean` | `hasDynamicProperty​(java.lang.String name)` | Returns whether a dynamic property is defined.
    `protected boolean` | `isChildable()` | Returns whether this component can have a child.
    `boolean` | `isInline()` | Returns whether this is an inline macro.
    `void` | `recreate()` | Detaches all child components and then recreate them by use of `compose()`.
    `protected void` | `renderProperties​(ContentRenderer renderer)` | Renders the content of this component, excluding the enclosing tags and children.
    `void` | `setDynamicProperty​(java.lang.String name, java.lang.Object value)` | Sets a property with the specified name and value.
    `void` | `setEnclosingTag​(java.lang.String tag)` | Sets the the name of the enclosing tag for this macro component.
    `boolean` | `setInlineParent​(Component parent, Component beforeSibling)` | Sets the parent to the given one and insert the children of the inline macro right before the given sibling (beforeSibling).
    `void` | `setMacroURI​(java.lang.String uri)` | Sets the macro URI.
    `void` | `setPage​(Page page)` | Changes the page.
    `void` | `setParent​(Component parent)` | Changes the parent.

    - ### Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

      `addSclass, evalCSSFlex, focus, getAction, getClientAction, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, getPropertyAccess, getRenderdefer, getSclass, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZindex, getZIndex, removeSclass, removeSclass, service, setAction, setClass, setClientAction, setDraggable, setDroppable, setFocus, setHeight, setHeight0, setHeightDirectly, setHflex, setHflex0, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTabindex, setTabindex, setTooltiptext, setTop, setTopDirectly, setVflex, setVflex0, setVflexDirectly, setWidth, setWidth0, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly`

    - ### Methods inherited from class org.zkoss.zk.ui.AbstractComponent

      `addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, beforeParentChanged, destroyIndexCacheMap, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, disableHostChanged, enableBindingAnnotation, enableHostChanged, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getCallback, getChildren, getClientAttribute, getClientDataAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getForwards, getId, getIndexCacheMap, getLastChild, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttributeNames, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, initIndexCacheMap, insertBefore, invalidate, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, onParentChanged, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, renderPropertiesOnly, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setMold, setPageBefore, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.zkoss.zk.ui.IdSpace

      `getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, hasFellow, hasFellow`

    - ### Methods inherited from interface org.zkoss.zk.ui.ext.Scope

      `addScopeListener, getAttribute, hasAttribute, removeAttribute, removeScopeListener, setAttribute`

- - ### Field Detail

    - #### _resolvers

          protected final java.util.List<VariableResolver> _resolvers

      A list of resolvers (never null). A variable resolver is added automatically if `VariableResolver` was annotated.

  - ### Constructor Detail

    - #### HtmlMacroComponent

          public HtmlMacroComponent()

  - ### Method Detail

    - #### getWidgetClass

          public java.lang.String getWidgetClass()

      Returns the component class (a.k.a., widget type), "zk.Macro".
      Specified by:
        `getWidgetClass` in interface `Component`
      Overrides:
        `getWidgetClass` in class `AbstractComponent`
      Since:
        5.0.0
      See Also:
        `Component.setWidgetClass(java.lang.String)`

    - #### getEnclosingTag

          public java.lang.String getEnclosingTag()

      Returns the name of the enclosing tag for this macro component.

      Default: div (since 7.0.1)

      Since:
        5.0.3

    - #### setEnclosingTag

          public void setEnclosingTag​(java.lang.String tag)

      Sets the the name of the enclosing tag for this macro component.

      Default: div (since 7.0.1)

      Since:
        5.0.3

    - #### afterCompose

          public void afterCompose()

      Creates the child components after apply dynamic properties `setDynamicProperty(java.lang.String, java.lang.Object)`.

      If a macro component is created by ZK loader, this method is invoked automatically. Developers rarely need to invoke this method.

      Default: it invokes `compose()` to compose the macro component.

      Instead of overriding this method, it is suggested to override `compose()`, since all other methods depend on `compose()` (rather than `afterCompose()`).

      Specified by:
        `afterCompose` in interface `AfterCompose`

    - #### compose

          protected void compose()

      Composes the macro component. It is called by `afterCompose()` and others to do the rendering based on `getMacroURI()`.

      The second invocation is ignored. If you want to recreate child components, use `recreate()` instead.

      If this is an line macro, this method is invoked automatically if `setParent(org.zkoss.zk.ui.Component)` or `setPage(org.zkoss.zk.ui.Page)` called

      By default, supports auto forward events and wire accessible variables to this component.

      Since:
        5.0.5

    - #### getMacroURI

          public java.lang.String getMacroURI()

      Description copied from interface: `Macro`
      Returns the macro URI.

      If `Macro.setMacroURI(java.lang.String)` wasn't called, it returns the URI defined in the macro definition.

      Specified by:
        `getMacroURI` in interface `Macro`

    - #### setMacroURI

          public void setMacroURI​(java.lang.String uri)

      Description copied from interface: `Macro`
      Sets the macro URI. It affects only this component.

      Note: this method calls `Macro.recreate()` automatically if uri is changed.

      Specified by:
        `setMacroURI` in interface `Macro`
      Parameters:
        `uri` - the URI of this macro. If null, the default is used.

    - #### recreate

          public void recreate()

      Detaches all child components and then recreate them by use of `compose()`.
      Specified by:
        `recreate` in interface `Macro`

    - #### isInline

          public boolean isInline()

      Description copied from interface: `Macro`
      Returns whether this is an inline macro. The only way to create an inline macro is by use of `ComponentDefinition.newInstance(org.zkoss.zk.ui.Page, java.lang.String)`.
      Specified by:
        `isInline` in interface `Macro`

    - #### setParent

          public void setParent​(Component parent)

      Changes the parent.

      Note: if this is an inline macro (`isInline()`), this method actually changes the parent of all components created from the macro URI. In other word, an inline macro behaves like a controller of the components it created. It doesn't belong to any page or parent. Moreover, `compose()` is called automatically if it is not called (and this is an inline macro).

      Specified by:
        `setParent` in interface `Component`
      Overrides:
        `setParent` in class `AbstractComponent`

    - #### setInlineParent

          public boolean setInlineParent​(Component parent,
                                         Component beforeSibling)

      Description copied from interface: `Macro`
      Sets the parent to the given one and insert the children of the inline macro right before the given sibling (beforeSibling).

      This method is used only internally.

      Notice that when `AbstractComponent.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)` is called to insert an inline macro (`Macro.isInline()`), the invocation will be forwarded to this method. It is called only `Macro.isInline()` is true.

      Specified by:
        `setInlineParent` in interface `Macro`
      Parameters:
        `parent` - the parent
        `beforeSibling` - a child of the parent that the macro component will be inserted before
      Returns:
        if it has been added successfully

    - #### setPage

          public void setPage​(Page page)

      Changes the page.

      Note: if this is an inline macro (`isInline()`), this method actually changes the page of all components created from the macro URI. In other word, an inline macro behaves like a controller of the components it created. It doesn't belong to any page or parent. Moreover, `compose()` is called automatically if it is not called (and this is an inline macro).

      Specified by:
        `setPage` in interface `Component`
      Overrides:
        `setPage` in class `AbstractComponent`
      See Also:
        `ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page)`, `ComponentCtrl.onPageDetached(org.zkoss.zk.ui.Page)`

    - #### isChildable

          protected boolean isChildable()

      Description copied from class: `AbstractComponent`
      Returns whether this component can have a child.

      Default: return true (means it can have children).

      Overrides:
        `isChildable` in class `AbstractComponent`

    - #### clone

          public java.lang.Object clone()

      Description copied from interface: `Component`
      Clones the component. All of its children and descendants are cloned. Also, ID are preserved.
      Specified by:
        `clone` in interface `Component`
      Overrides:
        `clone` in class `HtmlBasedComponent`
      Returns:
        the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.

    - #### hasDynamicProperty

          public boolean hasDynamicProperty​(java.lang.String name)

      Description copied from interface: `DynamicPropertied`
      Returns whether a dynamic property is defined.
      Specified by:
        `hasDynamicProperty` in interface `DynamicPropertied`

    - #### getDynamicProperties

          public java.util.Map<java.lang.String,​java.lang.Object> getDynamicProperties()

      Description copied from interface: `DynamicPropertied`
      Returns all available dynamic properties.
      Specified by:
        `getDynamicProperties` in interface `DynamicPropertied`

    - #### getDynamicProperty

          public java.lang.Object getDynamicProperty​(java.lang.String name)

      Description copied from interface: `DynamicPropertied`
      Returns the property value of the specified name.
      Specified by:
        `getDynamicProperty` in interface `DynamicPropertied`

    - #### setDynamicProperty

          public void setDynamicProperty​(java.lang.String name,
                                         java.lang.Object value)
                                  throws WrongValueException

      Description copied from interface: `DynamicPropertied`
      Sets a property with the specified name and value.

      If a component supports only String-type values, it could use org.zkoss.lang.Objects.toString() to convert the value to a String instance.

      Specified by:
        `setDynamicProperty` in interface `DynamicPropertied`
      Throws:
        `WrongValueException`

    - #### renderProperties

          protected void renderProperties​(ContentRenderer renderer)
                                   throws java.io.IOException

      Description copied from class: `HtmlBasedComponent`
      Renders the content of this component, excluding the enclosing tags and children.

      See also ZK Client-side Reference: Property Rendering

      Overrides:
        `renderProperties` in class `HtmlBasedComponent`
      Throws:
        `java.io.IOException`