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, 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 instant mode is supported automatically if the include component
is created by a ZUML page.
If you want to create it programmingly, you have to invoke
afterCompose()
after assigning the source (setSrc(java.lang.String)
).
- The isntance 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
).
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:
Include
(in defer mode) could include anything include ZUML,
JSP or any other
servlet, while a macro component could embed only a ZUML page.
- 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()
.
Include
(in defer mode) creates components in the Rendering phase,
while a macro component creates components in HtmlMacroComponent.afterCompose()
.
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
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 |
Include
public Include()
Include
public Include(java.lang.String src)
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.