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:
- 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:
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>
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 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 |
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 |
CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE |
Methods inherited from class org.zkoss.zul.impl.XulElement |
clone, getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip |
Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent |
focus, getAction, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZindex, getZIndex, service, setAction, setClass, setDraggable, setDroppable, setFocus, setHeight, setHeightDirectly, setHflex, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTooltiptext, setTop, setTopDirectly, setVflex, setWidth, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly |
Methods inherited from class org.zkoss.zk.ui.AbstractComponent |
addAnnotation, addAnnotation, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addScopeListener, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, beforeParentChanged, didActivate, didActivate, didDeserialize, didDeserialize, disableClientUpdate, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getChildren, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getStubonly, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageDetached, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, removeScopeListener, render, render, render, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setStubonly, setStubonly, setTemplate, setVisible, setVisibleDirectly, setWidgetAttribute, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, willPassivate, willPassivate, willSerialize, willSerialize |
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 |
Include
public Include()
Include
public Include(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.
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,
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 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
Copyright © 2014. All rights reserved.