public class Include extends XulElement implements Includer, DynamicPropertied, AfterCompose, IdSpace
Non-XUL extension.
If this component is the only child of its parent, the default width and height will become 100%.
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:
afterCompose()
after assigning the source (setSrc(java.lang.String)
).setProgressing(boolean)
nor
setLocalized(boolean)
Script
).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.
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).
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.
Include
Include
(in defer mode) could include anything include ZUML,
JSP or any other
servlet, while a macro component could embed only a ZUML page.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>
Iframe
,
Serialized FormHtmlBasedComponent.ExtraCtrl
AbstractComponent.Children
_zclass
APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE
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 and Description |
---|
Include() |
Include(java.lang.String src) |
Modifier and Type | Method and Description |
---|---|
void |
afterCompose()
Invokes after ZK loader creates this component,
initializes it and composes all its children, if any.
|
void |
clearDynamicProperties()
Removes all dynamic properties.
|
void |
detach()
Detaches this component such that it won't belong to any page.
|
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 |
getEnclosingTag()
Returns the name of the enclosing tag.
|
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 |
onAfterCompose() |
void |
onEchoInclude()
Internal use only.
|
void |
onPageAttached(Page newpage,
Page oldpage)
Default: handles special event listeners.
|
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 |
setEnclosingTag(java.lang.String tag)
Sets the the name of the enclosing tag
Default: div
|
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 |
setRenderingResult(java.lang.String result)
Sets the rendering result
It is called when the child page (
Includer.getChildPage() ) has
been rendered. |
void |
setSrc(java.lang.String src)
Sets the src.
|
clone, getContext, getCtrlKeys, getPopup, getPropertyAccess, getTooltip, setContext, setContext, setContextAttributes, setCtrlKeys, setPopup, setPopup, setPopupAttributes, setTooltip, setTooltip, setTooltipAttributes
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
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, isInitialized, 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
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, hasFellow, hasFellow
addScopeListener, getAttribute, getAttribute, getAttributes, hasAttribute, hasAttribute, removeAttribute, removeAttribute, removeScopeListener, setAttribute, setAttribute
invalidatePartial
public void setProgressing(boolean progressing)
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.
public boolean getProgressing()
MZul.PLEASE_WAIT
message before a long operation.
Default: false.
public void onEchoInclude()
public java.lang.String getSrc()
Default: null.
public void setSrc(java.lang.String src)
If src is changed, the whole component is invalidate. Thus, you want to smart-update, you have to override this method.
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.setDynamicProperty(java.lang.String, java.lang.Object)
public void detach()
Component
Component.setParent(org.zkoss.zk.ui.Component)
or Component.setPage(org.zkoss.zk.ui.Page)
to
attach it to any page, it will be removed automatically
(from the client) after the current event is processed.detach
in interface Component
detach
in class AbstractComponent
public java.lang.String getMode()
Default: auto (since 5.0.0).
public void setMode(java.lang.String mode) throws WrongValueException
mode
- the inclusion mode: auto, instant or defer.WrongValueException
public java.lang.String getEnclosingTag()
Default: div
public void setEnclosingTag(java.lang.String tag)
Default: div
public boolean isLocalized()
Default: false;
public void setLocalized(boolean localized)
public boolean isComment()
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">
<!--
//the content of a.xml
-->
</div>
Notice that it is ignored in the instance mode (getMode()
).
public void setComment(boolean comment)
isComment()
public Page getChildPage()
Includer
getChildPage
in interface Includer
public void setChildPage(Page page)
Includer
Used only for implementing an includer component (such as
Include
).
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.
Notice that, like Includer.setRenderingResult(java.lang.String)
, it is called only if
the included page is a ZUML document.
setChildPage
in interface Includer
public void setRenderingResult(java.lang.String result)
Includer
Includer.getChildPage()
) has
been rendered. The includer can then generate it to the output
in the way it'd like.
Used only for implementing an includer component (such as
Include
).
Notice that, like Includer.setChildPage(org.zkoss.zk.ui.Page)
, it is called only if
the included page is a ZUML document.
setRenderingResult
in interface Includer
public void onPageAttached(Page newpage, Page oldpage)
AbstractComponent
onPageAttached
in interface ComponentCtrl
onPageAttached
in class AbstractComponent
newpage
- the new page (never null).oldpage
- the previous page, if any, or null if it didn't
belong to any page.ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page)
public void onAfterCompose()
public void afterCompose()
AfterCompose
afterCompose
in interface AfterCompose
public boolean hasDynamicProperty(java.lang.String name)
hasDynamicProperty
in interface DynamicPropertied
public java.lang.Object getDynamicProperty(java.lang.String name)
getDynamicProperty
in interface DynamicPropertied
setDynamicProperty(java.lang.String, java.lang.Object)
public void setDynamicProperty(java.lang.String name, java.lang.Object value)
For example, if setDynamicProperty("abc", new Integer(4)) is called,
then the included page can retrieved the abc property
by use of ${reqestScope.abc}
setDynamicProperty
in interface DynamicPropertied
public void clearDynamicProperties()
public void invalidate()
invalidate
in interface Component
invalidate
in class AbstractComponent
protected boolean isChildable()
isChildable
in class AbstractComponent
protected void renderProperties(ContentRenderer renderer) throws java.io.IOException
HtmlBasedComponent
renderProperties
in class XulElement
java.io.IOException
Copyright © 2005-2021 Potix Corporation. All Rights Reserved.