Package org.zkoss.zuti.zul

## Class Apply

- java.lang.Object
- - org.zkoss.zk.ui.AbstractComponent
  - - org.zkoss.zk.ui.HtmlShadowElement
    - - org.zkoss.zuti.zul.TemplateBasedShadowElement
      - - org.zkoss.zuti.zul.Apply

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

      public class Apply
      extends TemplateBasedShadowElement
      implements DynamicPropertied

  The apply tag allows you to choose which `template` to be applied. You specify the template's name using the `template` attribute or the template's URI using the `templateURI` attribute.

  ### Passing Parameters

  There are two ways to pass parameters to the apply shadow:

  First, you can use `setDynamicProperty(java.lang.String, java.lang.Object)`, or, in ZUL,

      <apply templateURI="/WEB-INF/mypage" arg="something"/>

  Second, you can use the query string:

      <apply templateURI="/WEB-INF/mypage?arg=something"/>

  With the query string, you can pass only the String values. and the parameter can be accessed by `Execution.getArg()` Or, you can access it with the `arg` variable in EL expressions.

  Since:
    8.0.0
  Author:
    jumperchen
  See Also:
    Serialized Form

- - ### Nested Class Summary

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

      `HtmlShadowElement.Direction`

    - ### 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.Map<java.lang.String,​java.lang.Object>` | `_props` |

    - ### Fields inherited from class org.zkoss.zuti.zul.TemplateBasedShadowElement

      `_dirtyBinding, FOREACH_RENDERED_COMPONENTS, ON_BINDING_READY, SHADOW_VARIABLE`

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

      `_afterComposed, _dynamicValue, BIND_ANNO, BINDER, FOREACH_IN_RENDER, INIT_ANNO, LOAD_ANNO, ON_REBUILD_SHADOW_TREE_LATER, REFERENCE_ANNO, SAVE_ANNO, SKIP_DISTRIBUTED_CHILDREN_PROPERTY_CHANGE`

    - ### 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
    --- | ---
    `Apply()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.Object` | `clone()` | Clones the component.
    `protected void` | `compose​(Component host)` | Composes from template name and then template uri, if any.
    `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.
    `PropertyAccess` | `getPropertyAccess​(java.lang.String prop)` | Returns the corresponding property access object from the given property name, if any.
    `java.lang.String` | `getTemplate()` | Returns the template name
    `java.lang.String` | `getTemplateURI()` |
    `boolean` | `hasDynamicProperty​(java.lang.String name)` | Returns whether a dynamic property is defined.
    `protected boolean` | `isEffective()` | Returns whether the shadow element is effective
    `protected Template` | `resolveTemplate()` | Return the template, if any, the default implementation will look up the template where in its parent shadow or its shadow host.
    `java.lang.Object` | `resolveVariable​(Component child, java.lang.String name, boolean recurse)` | Returns the variable associated with this base component or null if not found.
    `void` | `setDynamicProperty​(java.lang.String name, java.lang.Object value)` | Sets a property with the specified name and value.
    `void` | `setTemplate​(java.lang.String template)` | Sets the template name to apply.
    `void` | `setTemplateURI​(java.lang.String templateURI)` | Sets the template uri.

    - ### Methods inherited from class org.zkoss.zuti.zul.TemplateBasedShadowElement

      `addBindingListener, afterCompose, detach, docheck0, isBindingReady, isDirtyBinding, isDynamicValue, onChildAdded, onChildRemoved, rebuildSubShadowTree, removeBindingListener`

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

      `afterHostChildAdded, afterHostChildRemoved, asShadow, beforeChildAdded, beforeHostChildAdded, beforeHostChildRemoved, beforeHostParentChanged, beforeParentChanged, clearChildren, destroyIndexCacheMap, getDistributedChildren, getFirstInsertion, getIndex, getIndexCacheMap, getLastInsertion, getNextInsertion, getNextInsertionComponentIfAny, getPreviousInsertion, getPreviousInsertionComponentIfAny, getShadowHost, getShadowHostIfAny, initClone, initIndexCacheMap, inRange, invalidate, isDynamicValue, mergeSubTree, mergeToHost, onHostAttached, onHostChildAdded, onHostChildRemoved, onHostDetached, recreate, removeFromParent, setDynamicValue, setParent, setPrevInsertion, setShadowHost, shrinkRange, stretchRange, toString, updateFirstInsertion, updateLastInsertion, updateNextInsertion, updatePreviousInsertion, updateSubBindingAnnotationCount`

    - ### 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, beforeChildRemoved, 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, getExtraCtrl, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getForwards, getId, getLastChild, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, insertBefore, isChildable, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onPageAttached, onPageDetached, onParentChanged, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, renderProperties, renderPropertiesOnly, replace, response, response, response, service, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, updateByClient, willPassivate, willPassivate, willSerialize, willSerialize`

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

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

- - ### Field Detail

    - #### _props

          protected java.util.Map<java.lang.String,​java.lang.Object> _props

  - ### Constructor Detail

    - #### Apply

          public Apply()

  - ### Method Detail

    - #### getTemplate

          public java.lang.String getTemplate()

      Returns the template name

      Default: empty string

    - #### setTemplate

          public void setTemplate​(java.lang.String template)

      Sets the template name to apply.

      One cannot set both template and template URI in the same time.

      Notice that, the template enclosed with <apply> tag will be created only when both template and template URI are not set.

    - #### setTemplateURI

          public void setTemplateURI​(java.lang.String templateURI)

      Sets the template uri.

      If templateURI is changed, the whole shadow is recreated. One cannot set both template and template URI in the same time.

      Notice that, the template enclosed with <apply> tag will be created only when both template and template URI are not set.

      Parameters:
        `templateURI` - the template URI. If null or empty, nothing is applied. You can specify the template URI with the query string and they will become a map of parameters that is accessible by the arg variable in EL, or by `Execution.getArg()`. For example, if "/a.zul?b=c" is specified, you can access the parameter with ${arg.b} in a.zul.
      See Also:
        `setDynamicProperty(java.lang.String, java.lang.Object)`

    - #### getTemplateURI

          public java.lang.String getTemplateURI()

    - #### resolveTemplate

          protected Template resolveTemplate()

      Return the template, if any, the default implementation will look up the template where in its parent shadow or its shadow host.
      Returns:
        Template

    - #### resolveVariable

          public java.lang.Object resolveVariable​(Component child,
                                                  java.lang.String name,
                                                  boolean recurse)

      Description copied from interface: `ShadowElementCtrl`
      Returns the variable associated with this base component or null if not found.

      Notice that it doesn't check any variable defined in `VariableResolver` (of `Page.addVariableResolver(org.zkoss.xel.VariableResolver)`).

      Specified by:
        `resolveVariable` in interface `ShadowElementCtrl`
      Overrides:
        `resolveVariable` in class `HtmlShadowElement`
      Parameters:
        `child` - the child component of the shadow host
        `recurse` - whether to look up the parent shadow for the existence of the variable.
        If recurse is true, it will look up all parents until found.

    - #### compose

          protected void compose​(Component host)

      Composes from template name and then template uri, if any.
      Overrides:
        `compose` in class `TemplateBasedShadowElement`
      Parameters:
        `host` - the shadow host component, never null.

    - #### isEffective

          protected boolean isEffective()

      Description copied from class: `HtmlShadowElement`
      Returns whether the shadow element is effective
      Overrides:
        `isEffective` in class `TemplateBasedShadowElement`

    - #### 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`

    - #### 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`

    - #### 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`

    - #### 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`

    - #### getPropertyAccess

          public PropertyAccess getPropertyAccess​(java.lang.String prop)

      Description copied from interface: `ComponentCtrl`
      Returns the corresponding property access object from the given property name, if any.
      Specified by:
        `getPropertyAccess` in interface `ComponentCtrl`
      Overrides:
        `getPropertyAccess` in class `AbstractComponent`
      Parameters:
        `prop` - the name of the property
      Returns:
        null it means not to support for the property name.

    - #### 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 `TemplateBasedShadowElement`
      Returns:
        the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.