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 when
#afterComposeis 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
#afterComposeafter assigning the source (
#setSrc).
- The instant mode doesn't support
#setProgressing nor
#setLocalized
- 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 (
org.zkoss.zk.ui.Page)
is created and added to the current desktop.
You can access them only via inter-page API (see
org.zkoss.zk.ui.Path).
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).
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 or
#setLocalizedwith 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, 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#getParameteror 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)
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 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
org.zkoss.zk.ui.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
org.zkoss.zk.ui.Component#getChildren.
-
Include (in defer mode) creates components in the Rendering phase,
while a macro component creates components in
org.zkoss.zk.ui.HtmlMacroComponent#afterCompose.
-
Include#invalidate (in defer mode) will cause it to re-include
the page (and then recreate the page if it includes a ZUML page).
However,
org.zkoss.zk.ui.HtmlMacroComponent#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
org.zkoss.zk.ui.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).