org.zkoss.zul
Class Include

java.lang.Object
  extended by org.zkoss.zk.ui.AbstractComponent
      extended by org.zkoss.zk.ui.HtmlBasedComponent
          extended by org.zkoss.zul.impl.XulElement
              extended by org.zkoss.zul.Include
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, HtmlBasedComponent, Component, AfterCompose, DynamicPropertied, Includer, Scope, IdSpace, ComponentCtrl, Include, XulElement

public class Include
extends XulElement
implements Include, Includer

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%.

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 fully backward compatibility).

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 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).

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).

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 pag 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>

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
 
Field Summary
 
Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent
_height, _left, _top, _width, _zclass
 
Fields inherited from class org.zkoss.zk.ui.AbstractComponent
_visible
 
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
CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE
 
Constructor Summary
Include()
           
Include(java.lang.String src)
           
 
Method Summary
 void afterCompose()
          Invokes after ZK loader creates this component, initializes it and composes all its children, if any.
 void clearDynamicProperties()
          Removes all dynamic properties.
 Page getChildPage()
          Returns the child page.
 java.lang.Object getDynamicProperty(java.lang.String name)
          Returns the parameter associated with the specified name, or null if not found.
 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 onEchoInclude()
          Internal use only.
protected  void redrawChildren(java.io.Writer out)
          Redraws childrens (and then recursively descandants).
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 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 setSrc(java.lang.String src)
          Sets the src.
 
Methods inherited from class org.zkoss.zul.impl.XulElement
getAction, getContext, getCtrlKeys, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip
 
Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent
focus, getDraggable, getDroppable, getHeight, getHflex, getLeft, getSclass, getStyle, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZindex, getZIndex, newExtraCtrl, service, setClass, setDraggable, setDroppable, setFocus, setHeight, setHflex, setLeft, setSclass, setStyle, setTooltiptext, setTop, setVflex, setWidth, setZclass, setZindex, setZIndex
 
Methods inherited from class org.zkoss.zk.ui.AbstractComponent
addAnnotation, addAnnotation, addClientEvent, addEventHandler, addEventListener, addForward, addForward, addForward, addForward, addMoved, addScopeListener, addSharedAnnotationMap, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, beforeParentChanged, clone, containsVariable, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableClientUpdate, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getChildren, getClientEvents, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getExtraCtrl, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, isInvalidated, isListenerAvailable, isVisible, newChildren, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, onWrongValue, redraw, removeAttribute, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, removeScopeListener, render, render, render, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, unsetVariable, updateByClient, willPassivate, willPassivate, willSerialize, willSerialize
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.zkoss.zul.impl.api.XulElement
getAction, getContext, getCtrlKeys, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip
 
Methods inherited from interface org.zkoss.zk.ui.api.HtmlBasedComponent
focus, getHeight, getLeft, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZclass, getZindex, getZIndex, setDraggable, setDroppable, setFocus, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex
 
Methods inherited from interface org.zkoss.zk.ui.Component
addEventListener, addForward, addForward, addForward, addForward, appendChild, applyProperties, clone, containsVariable, detach, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getChildren, getDefinition, getDesktop, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, isInvalidated, isListenerAvailable, isVisible, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setAuService, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, setWidgetListener, setWidgetOverride, unsetVariable
 
Methods inherited from interface org.zkoss.zk.ui.ext.Scope
addScopeListener, getAttribute, hasAttribute, removeAttribute, removeScopeListener, setAttribute
 
Methods inherited from interface org.zkoss.zk.ui.IdSpace
getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, hasFellow, hasFellow
 

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.

Default: false.

Specified by:
setProgressing in interface Include
Since:
3.0.4

getProgressing

public boolean getProgressing()
Returns whether to show the MZul.PLEASE_WAIT message before a long operation.

Default: false.

Specified by:
getProgressing in interface Include
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.

Specified by:
getSrc in interface Include

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.

Specified by:
setSrc in interface Include
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)

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).

Specified by:
getMode in interface Include
Since:
3.6.2

setMode

public void setMode(java.lang.String mode)
             throws WrongValueException
Sets the inclusion mode.

Specified by:
setMode in interface Include
Parameters:
mode - the inclusion mode: auto, instant or defer.
Throws:
WrongValueException
Since:
3.6.2

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;

Specified by:
isLocalized in interface Include

setLocalized

public void setLocalized(boolean localized)
Sets whether the source depends on the current Locale.

Specified by:
setLocalized in interface Include

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,

Then, it will generate
<div id="uuid">
<!--
 //the content of a.xml
-->

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 internally.

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.

Specified by:
setChildPage in interface Includer

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

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 retrived 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. Notice that all children will be detached 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

redrawChildren

protected void redrawChildren(java.io.Writer out)
                       throws java.io.IOException
Description copied from class: AbstractComponent
Redraws childrens (and then recursively descandants).

Default: it invokes AbstractComponent.redraw(java.io.Writer) for all its children.

If a derived class renders only a subset of its children (such as paging/cropping), it could override AbstractComponent.redrawChildren(java.io.Writer).

Overrides:
redrawChildren in class AbstractComponent
Throws:
java.io.IOException
See Also:
AbstractComponent.redraw(java.io.Writer)

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 Render Special Properties

Overrides:
renderProperties in class XulElement
Throws:
java.io.IOException


Copyright © 2005-2009 Potix Corporation. All Rights Reserved. SourceForge.net Logo