Include (ZK XUL Components 9.0.0 API)

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:

Serializable, Cloneable, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.ext.AfterCompose, org.zkoss.zk.ui.ext.DynamicPropertied, org.zkoss.zk.ui.ext.Includer, org.zkoss.zk.ui.ext.Scope, org.zkoss.zk.ui.IdSpace, org.zkoss.zk.ui.sys.ComponentCtrl
```
public class Include
extends XulElement
implements org.zkoss.zk.ui.ext.Includer, org.zkoss.zk.ui.ext.DynamicPropertied, org.zkoss.zk.ui.ext.AfterCompose, org.zkoss.zk.ui.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 (seePath).
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
  org.zkoss.zk.ui.HtmlBasedComponent.ExtraCtrl
- Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent
  org.zkoss.zk.ui.AbstractComponent.Children

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_PAGE_ATTACHED, AFTER_PAGE_DETACHED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

Constructor Summary

Constructors
Constructor and Description

Include()

Include(String src)

Constructors
Constructor and Description
`Include()`
`Include(String src)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`afterCompose()`
`void`	`clearDynamicProperties()` Removes all dynamic properties.
`void`	`detach()`
`org.zkoss.zk.ui.Page`	`getChildPage()`
`Object`	`getDynamicProperty(String name)` Returns the parameter associated with the specified name, or null if not found.
`String`	`getEnclosingTag()` Returns the name of the enclosing tag.
`String`	`getMode()` Returns the inclusion mode.
`boolean`	`getProgressing()` Returns whether to show the `MZul.PLEASE_WAIT` message before a long operation.
`String`	`getSrc()` Returns the src.
`boolean`	`hasDynamicProperty(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(org.zkoss.zk.ui.Page newpage, org.zkoss.zk.ui.Page oldpage)`
`protected void`	`renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer)`
`void`	`setChildPage(org.zkoss.zk.ui.Page page)`
`void`	`setComment(boolean comment)` Sets whether to generate the included content inside the HTML comment.
`void`	`setDynamicProperty(String name, Object value)` Adds a dynamic property that will be passed to the included page via the request's attribute.
`void`	`setEnclosingTag(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(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(String result)`
`void`	`setSrc(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, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZindex, getZIndex, removeSclass, removeSclass, service, setAction, setClass, 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, addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, beforeParentChanged, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, enableBindingAnnotation, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, 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, getId, getLastChild, getListenerIterator, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, insertBefore, invalidatePartial, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageDetached, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, 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, setWidgetAttribute, 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, getAttribute, getAttributes, hasAttribute, hasAttribute, removeAttribute, removeAttribute, removeScopeListener, setAttribute, setAttribute

- Constructor Detail
  - Include
```
public Include()
```
  - Include
```
public Include(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 String getSrc()
```
    Returns the src.
    Default: null.
  - setSrc
```
public void setSrc(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()
```
    Specified by:
    
    detach in interface org.zkoss.zk.ui.Component
    
    Overrides:
    
    detach in class org.zkoss.zk.ui.AbstractComponent
  - getMode
```
public 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(String mode)
             throws org.zkoss.zk.ui.WrongValueException
```
    Sets the inclusion mode.
    
    Parameters:
    
    mode - the inclusion mode: auto, instant or defer.
    
    Throws:
    
    org.zkoss.zk.ui.WrongValueException
    
    Since:
    
    3.6.2
  - getEnclosingTag
```
public String getEnclosingTag()
```
    Returns the name of the enclosing tag.
    Default: div
    
    Since:
    
    7.0.4
  - setEnclosingTag
```
public void setEnclosingTag(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">

</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 org.zkoss.zk.ui.Page getChildPage()
```
    Specified by:
    
    getChildPage in interface org.zkoss.zk.ui.ext.Includer
  - setChildPage
```
public void setChildPage(org.zkoss.zk.ui.Page page)
```
    Specified by:
    
    setChildPage in interface org.zkoss.zk.ui.ext.Includer
  - setRenderingResult
```
public void setRenderingResult(String result)
```
    Specified by:
    
    setRenderingResult in interface org.zkoss.zk.ui.ext.Includer
  - onPageAttached
```
public void onPageAttached(org.zkoss.zk.ui.Page newpage,
                           org.zkoss.zk.ui.Page oldpage)
```
    Specified by:
    
    onPageAttached in interface org.zkoss.zk.ui.sys.ComponentCtrl
    
    Overrides:
    
    onPageAttached in class org.zkoss.zk.ui.AbstractComponent
  - onAfterCompose
```
public void onAfterCompose()
```
  - afterCompose
```
public void afterCompose()
```
    Specified by:
    
    afterCompose in interface org.zkoss.zk.ui.ext.AfterCompose
  - hasDynamicProperty
```
public boolean hasDynamicProperty(String name)
```
    Returns whether a dynamic property is defined.
    
    Specified by:
    
    hasDynamicProperty in interface org.zkoss.zk.ui.ext.DynamicPropertied
  - getDynamicProperty
```
public Object getDynamicProperty(String name)
```
    Returns the parameter associated with the specified name, or null if not found.
    
    Specified by:
    
    getDynamicProperty in interface org.zkoss.zk.ui.ext.DynamicPropertied
    
    Since:
    
    3.0.4
    
    See Also:
    
    setDynamicProperty(java.lang.String, java.lang.Object)
  - setDynamicProperty
```
public void setDynamicProperty(String name,
                               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 org.zkoss.zk.ui.ext.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 org.zkoss.zk.ui.Component
    
    Overrides:
    
    invalidate in class org.zkoss.zk.ui.AbstractComponent
  - isChildable
```
protected boolean isChildable()
```
    Default: not childable.
    
    Overrides:
    
    isChildable in class org.zkoss.zk.ui.AbstractComponent
  - renderProperties
```
protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer)
                         throws IOException
```
    Overrides:
    
    renderProperties in class XulElement
    
    Throws:
    
    IOException

Class Include

The instant mode

The defer mode

The auto mode (default)

Passing Parameters

Macro Component versus Include

Custom Attribute

Nested Class Summary

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

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

Field Summary

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

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

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

Constructor Summary

Method Summary

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

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

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

Methods inherited from class java.lang.Object

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

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

Constructor Detail

Include

Include

Method Detail

setProgressing

getProgressing

onEchoInclude

getSrc

setSrc

detach

getMode

setMode

getEnclosingTag

setEnclosingTag

isLocalized

setLocalized

isComment

setComment

getChildPage

setChildPage

setRenderingResult

onPageAttached

onAfterCompose

afterCompose

hasDynamicProperty

getDynamicProperty

setDynamicProperty

clearDynamicProperties

invalidate

isChildable

renderProperties

Macro Component versus `Include`