Package org.zkoss.zul

## Class Include

- java.lang.Object
- - org.zkoss.zk.ui.AbstractComponent
  - - org.zkoss.zk.ui.HtmlBasedComponent
    - - org.zkoss.zul.impl.XulElement
      - - org.zkoss.zul.Include

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

      public class Include
      extends XulElement
      implements Includer, DynamicPropertied, AfterCompose, IdSpace

  Includes the result generated by any servlet, not limited to a ZUML page.

  Non-XUL extension.

  If this component is the only child of its parent, the default width and height will become 100%.

  ### The instant mode

  In the instant mode, the page to be included are loaded 'instantly' with `Execution.createComponents(org.zkoss.zk.ui.metainfo.PageDefinition, org.zkoss.zk.ui.Component, java.util.Map<?, ?>)` when `afterCompose()` is called. Furthermore, the components are created as the child components of this include component (like a macro component).

  Notices:

  - The instant mode is supported automatically if the include component is created by a ZUML page. If you want to create it programmatically, you have to invoke `afterCompose()` after assigning the source (`setSrc(java.lang.String)`).
  - The instant mode doesn't support `setProgressing(boolean)` nor `setLocalized(boolean)`
  - The directives of the included page won't be included. It means <?style?> won't be evaluated. Thus, if you want to embed JavaScript files or codes in a page that might be included, it is better to use the script component (`Script`).

  ### The defer mode

  In the defer mode (the only mode supported by ZK prior to 3.6.2), the page is included by servlet container (the `include` method of `javax.servlet.RequestDispatcher`) in the render phase (i.e., after all components are created). The page can be any servlet; not limited to a ZUML page.

  If it is eventually another ZUML page, a ZK page (`Page`) is created and added to the current desktop. You can access them only via inter-page API (see`Path`).

  Notice that if a non-ZUML page, such as HTML fragment, is included, the content might be evaluated before ZK widgets are instantiated and rendered (so-called mounted). Thus, the embedded JavaScript code might be evaluated early. If you prefer to run them later, you could either use `zk.afterMount(function(){...})` to defer the execute, or specify the custom attribute called `org.zkoss.zul.include.html.defer` to true.

  ### The auto mode (default)

  In the auto mode, the include component decides the mode based on the name specified in the src property (`setSrc(java.lang.String)`). If `src` is ended with the extension named `.zul` or `.zhtml`, the `instant` mode is assumed. Otherwise, the `defer` mode is assumed. Notice that if a query string is specified, the `defer` mode is assumed, too.

  Notice that invoking `setProgressing(boolean)` or `setLocalized(boolean)` with true will imply the `defer` mode (if the mode is `auto`).

  Backward Compatibility: Since 3.6.2, there are three modes: auto (default), instant and defer. The behavior prior to 3.6.2 is the same as the defer mode. The default mode is `auto` since 5.0. However, you can change it to `defer` by specifying a library property named `org.zkoss.zul.include.mode` (for backward compatibility).

  ### Passing Parameters

  There are two ways to pass parameters to the included page:

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

      <include src="/WEB-INF/mypage" arg="something"/>

  Second, you can use the query string:

      <include src="/WEB-INF/mypage?arg=something"/>

  With the query string, you can pass only the String values. and the parameter can be accessed by `Execution.getParameter(java.lang.String)` or javax.servlet.ServletRequest's getParameter. Or, you can access it with the param variable in EL expressions.

  On the other hand, the dynamic properties (`setDynamicProperty(java.lang.String, java.lang.Object)`) are passed to the included page thru the request's attributes You can pass any type of objects you want. In the included page, you can access them by use of `Execution.getAttribute(java.lang.String)` or javax.servlet.ServletRequest's getAttribute. Or, you can access with the requestScope variable in EL expressions.

  ### Macro Component versus `Include`

  If the include component is in the instant mode, it is almost the same as a macro component. On the other hand, if in the defer mode, they are different:
  1. `Include` (in defer mode) could include anything include ZUML, JSP or any other servlet, while a macro component could embed only a ZUML page.
  2. If `Include` (in defer mode) includes a ZUML page, a `Page` instance is created which is owned by `Include`. On the other hand, a macro component makes the created components as the direct children -- i.e., you can browse them with `Component.getChildren()`.
  3. `Include` (in defer mode) creates components in the Rendering phase, while a macro component creates components in `HtmlMacroComponent.afterCompose()`.
  4. `invalidate()` (in defer mode) will cause it to re-include the page (and then recreate the page if it includes a ZUML page). However, `AbstractComponent.invalidate()` just causes it to redraw and update the content at the client -- like any other component does. To re-create, you have to invoke `HtmlMacroComponent.recreate()`.

  In additions to macro and `Include`, you can use the fulfill attribute as follows: `<div fulfill="=/my/foo.zul">...</div>`

  ### Custom Attribute

  org.zkoss.zul.include.html.defer
    [default: false] Whether to defer the rendering of non-ZUML page until all widgets are instantiated and rendered at client (so-called mounted).
  Author:
    tomyeh
  See Also:
    `Iframe`, 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 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
    --- | ---
    `Include()` |
    `Include​(java.lang.String src)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `afterCompose()` | Invokes after ZK loader creates this component, initializes it and composes all its children, if any.
    `void` | `clearDynamicProperties()` | Removes all dynamic properties.
    `void` | `detach()` | Detaches this component such that it won't belong to any page.
    `Page` | `getChildPage()` | Returns the child page.
    `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 parameter associated with the specified name, or null if not found.
    `java.lang.String` | `getEnclosingTag()` | Returns the name of the enclosing tag.
    `java.lang.String` | `getMode()` | Returns the inclusion mode.
    `boolean` | `getProgressing()` | Returns whether to show the `MZul.PLEASE_WAIT` message before a long operation.
    `java.lang.String` | `getSrc()` | Returns the src.
    `boolean` | `hasDynamicProperty​(java.lang.String name)` | Returns whether a dynamic property is defined.
    `void` | `invalidate()` | Invalidates this component.
    `protected boolean` | `isChildable()` | Default: not childable.
    `boolean` | `isComment()` | Returns whether to generate the included content inside the HTML comment.
    `boolean` | `isLocalized()` | Returns whether the source depends on the current Locale.
    `void` | `onAfterCompose()` |
    `void` | `onEchoInclude()` | Internal use only.
    `void` | `onPageAttached​(Page newpage, Page oldpage)` | Default: handles special event listeners.
    `protected void` | `renderProperties​(ContentRenderer renderer)` | Renders the content of this component, excluding the enclosing tags and children.
    `void` | `setChildPage​(Page page)` | Sets the child page.
    `void` | `setComment​(boolean comment)` | Sets whether to generate the included content inside the HTML comment.
    `void` | `setDynamicProperty​(java.lang.String name, java.lang.Object value)` | Adds a dynamic property that will be passed to the included page via the request's attribute.
    `void` | `setEnclosingTag​(java.lang.String tag)` | Sets the the name of the enclosing tag
    `void` | `setLocalized​(boolean localized)` | Sets whether the source depends on the current Locale.
    `void` | `setMode​(java.lang.String mode)` | Sets the inclusion mode.
    `void` | `setProgressing​(boolean progressing)` | Sets whether to show the `MZul.PLEASE_WAIT` message before a long operation.
    `void` | `setRenderingResult​(java.lang.String result)` | Sets the rendering result It is called when the child page (`Includer.getChildPage()`) has been rendered.
    `void` | `setSrc​(java.lang.String src)` | Sets the src.

    - ### Methods inherited from class org.zkoss.zul.impl.XulElement

      `clone, getContext, getCtrlKeys, getPopup, getPropertyAccess, getTooltip, setContext, setContext, setContextAttributes, setCtrlKeys, setPopup, setPopup, setPopupAttributes, setTooltip, setTooltip, setTooltipAttributes`

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

      `addSclass, evalCSSFlex, focus, getAction, getClientAction, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, 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, 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, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, initIndexCacheMap, insertBefore, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, 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, setPage, setPageBefore, setParent, 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`

- - ### Constructor Detail

    - #### Include

          public Include()

    - #### Include

          public Include​(java.lang.String src)

  - ### Method Detail

    - #### setProgressing

          public void setProgressing​(boolean progressing)

      Sets whether to show the `MZul.PLEASE_WAIT` message before a long operation. This implementation will automatically use an echo event like `Events.echoEvent(String, org.zkoss.zk.ui.Component, String)` to suspend the including progress before using the `Clients.showBusy(String)` method to show the `MZul.PLEASE_WAIT` message at client side.

      If setProgressing(true) is called, the `defer` mode is enabled automatically if the current mode is `auto`.

      Default: false.

      Since:
        3.0.4

    - #### getProgressing

          public boolean getProgressing()

      Returns whether to show the `MZul.PLEASE_WAIT` message before a long operation.

      Default: false.

      Since:
        3.0.4

    - #### onEchoInclude

          public void onEchoInclude()

      Internal use only.
      Since:
        3.0.4

    - #### getSrc

          public java.lang.String getSrc()

      Returns the src.

      Default: null.

    - #### setSrc

          public void setSrc​(java.lang.String src)

      Sets the src.

      If src is changed, the whole component is invalidate. Thus, you want to smart-update, you have to override this method.

      Parameters:
        `src` - the source URI. If null or empty, nothing is included. You can specify the source URI with the query string and they will become a parameter that can be accessed by use of `Execution.getParameter(java.lang.String)` or javax.servlet.ServletRequest's getParameter. For example, if "/a.zul?b=c" is specified, you can access the parameter with ${param.b} in a.zul.
      See Also:
        `setDynamicProperty(java.lang.String, java.lang.Object)`

    - #### detach

          public void detach()

      Description copied from interface: `Component`
      Detaches this component such that it won't belong to any page. If you don't call `Component.setParent(org.zkoss.zk.ui.Component)` or `Component.setPage(org.zkoss.zk.ui.Page)` to attach it to any page, it will be removed automatically (from the client) after the current event is processed.
      Specified by:
        `detach` in interface `Component`
      Overrides:
        `detach` in class `AbstractComponent`

    - #### getMode

          public java.lang.String getMode()

      Returns the inclusion mode. There are three modes: auto, instant and defer. The behavior prior to 3.6.2 is the same as the defer mode.

      Default: auto (since 5.0.0).

      Since:
        3.6.2

    - #### setMode

          public void setMode​(java.lang.String mode)
                       throws WrongValueException

      Sets the inclusion mode.
      Parameters:
        `mode` - the inclusion mode: auto, instant or defer.
      Throws:
        `WrongValueException`
      Since:
        3.6.2

    - #### getEnclosingTag

          public java.lang.String getEnclosingTag()

      Returns the name of the enclosing tag.

      Default: div

      Since:
        7.0.4

    - #### setEnclosingTag

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

      Sets the the name of the enclosing tag

      Default: div

      Since:
        7.0.4

    - #### isLocalized

          public boolean isLocalized()

      Returns whether the source depends on the current Locale. If true, it will search xxx_en_US.yyy, xxx_en.yyy and xxx.yyy for the proper content, where src is assumed to be xxx.yyy.

      Default: false;

    - #### setLocalized

          public void setLocalized​(boolean localized)

      Sets whether the source depends on the current Locale.

    - #### isComment

          public boolean isComment()

      Returns whether to generate the included content inside the HTML comment.

      Default: false.

      It is useful if you want to include non-HTML content. For example,

          <include src="a.xml" comment="true"/>

      Then, it will generate

          <div id="uuid">
          <!--
           //the content of a.xml
          -->
          </div>

      Notice that it is ignored in the instance mode (`getMode()`).

      Since:
        5.0.0

    - #### setComment

          public void setComment​(boolean comment)

      Sets whether to generate the included content inside the HTML comment.
      Since:
        5.0.0
      See Also:
        `isComment()`

    - #### getChildPage

          public Page getChildPage()

      Description copied from interface: `Includer`
      Returns the child page.
      Specified by:
        `getChildPage` in interface `Includer`

    - #### setChildPage

          public void setChildPage​(Page page)

      Description copied from interface: `Includer`
      Sets the child page.

      Used only for implementing an includer component (such as `Include`).

      Note: the child page is actually maintained by the included page, so the implementation of this method needs only to store the page in a transient member.

      Notice that, like `Includer.setRenderingResult(java.lang.String)`, it is called only if the included page is a ZUML document.

      Specified by:
        `setChildPage` in interface `Includer`

    - #### setRenderingResult

          public void setRenderingResult​(java.lang.String result)

      Description copied from interface: `Includer`
      Sets the rendering result It is called when the child page (`Includer.getChildPage()`) has been rendered. The includer can then generate it to the output in the way it'd like.

      Used only for implementing an includer component (such as `Include`).

      Notice that, like `Includer.setChildPage(org.zkoss.zk.ui.Page)`, it is called only if the included page is a ZUML document.

      Specified by:
        `setRenderingResult` in interface `Includer`

    - #### onPageAttached

          public void onPageAttached​(Page newpage,
                                     Page oldpage)

      Description copied from class: `AbstractComponent`
      Default: handles special event listeners.
      Specified by:
        `onPageAttached` in interface `ComponentCtrl`
      Overrides:
        `onPageAttached` in class `AbstractComponent`
      Parameters:
        `newpage` - the new page (never null).
        `oldpage` - the previous page, if any, or null if it didn't belong to any page.
      See Also:
        `ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page)`

    - #### onAfterCompose

          public void onAfterCompose()

    - #### afterCompose

          public void afterCompose()

      Description copied from interface: `AfterCompose`
      Invokes after ZK loader creates this component, initializes it and composes all its children, if any.
      Specified by:
        `afterCompose` in interface `AfterCompose`

    - #### hasDynamicProperty

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

      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)

      Returns the parameter associated with the specified name, or null if not found.
      Specified by:
        `getDynamicProperty` in interface `DynamicPropertied`
      Since:
        3.0.4
      See Also:
        `setDynamicProperty(java.lang.String, java.lang.Object)`

    - #### setDynamicProperty

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

      Adds a dynamic property that will be passed to the included page via the request's attribute.

      For example, if setDynamicProperty("abc", new Integer(4)) is called, then the included page can retrieved the abc property by use of `${reqestScope.abc}`

      Specified by:
        `setDynamicProperty` in interface `DynamicPropertied`
      Since:
        3.0.4

    - #### clearDynamicProperties

          public void clearDynamicProperties()

      Removes all dynamic properties.
      Since:
        5.0.1

    - #### invalidate

          public void invalidate()

      Invalidates this component. It works for both the instant and defer mode. Notice that all children will be detached (the instant mode) and the page will be reloaded (and new children will be created).
      Specified by:
        `invalidate` in interface `Component`
      Overrides:
        `invalidate` in class `AbstractComponent`

    - #### isChildable

          protected boolean isChildable()

      Default: not childable.
      Overrides:
        `isChildable` in class `AbstractComponent`

    - #### 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 `XulElement`
      Throws:
        `java.io.IOException`