org.zkoss.zul.api
Interface Include

All Superinterfaces:
AfterCompose, java.lang.Cloneable, Component, DynamicPropertied, HtmlBasedComponent, IdSpace, Scope, java.io.Serializable, XulElement
All Known Implementing Classes:
Include

public interface Include
extends XulElement, DynamicPropertied, AfterCompose, IdSpace

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

Non-XUL extension.

Since 3.6.2, there are three modes: auto, instant and defer (default). The behavior prior to 3.6.2 is the same as the defer mode. To be fully backward compatible, the default mode is defer. However, we recommend you change it by specifying a library variable named org.zkoss.zul.include.mode to be auto, since the auto mode is more intuitive and easier to handle.

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.afterCompose() is called. Furthermore, the components are created as the child components of this include component (like a macro component).

Notices:

The defer mode (default)

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

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 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 DynamicPropertied.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 (DynamicPropertied.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. Component.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>

Since:
3.5.2
Author:
tomyeh
See Also:
Iframe

Field Summary
 
Fields inherited from interface org.zkoss.zk.ui.Component
APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE
 
Method Summary
 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 isLocalized()
          Returns whether the source depends on the current Locale.
 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 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, invalidate, 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.ext.DynamicPropertied
getDynamicProperty, hasDynamicProperty, setDynamicProperty
 
Methods inherited from interface org.zkoss.zk.ui.ext.AfterCompose
afterCompose
 
Methods inherited from interface org.zkoss.zk.ui.IdSpace
getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, hasFellow, hasFellow
 

Method Detail

setProgressing

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.


getProgressing

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

Default: false.


getSrc

java.lang.String getSrc()
Returns the src.

Default: null.


setSrc

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:
DynamicPropertied.setDynamicProperty(java.lang.String, java.lang.Object)

isLocalized

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;

Since:
3.6.2

setLocalized

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

Since:
3.6.2

getMode

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.

It is recommended to use the auto mode if possible The reason to have defer as the default is to be backward compatible.

Default: defer.

Since:
3.6.2

setMode

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


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