org.zkoss.zul.api
Interface Include

All Superinterfaces:

java.lang.Cloneable, Component, DynamicPropertied, HtmlBasedComponent, Scope, java.io.Serializable, XulElement

All Known Implementing Classes:

Include

public interface Include
extends XulElement, DynamicPropertied

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

Non-XUL extension.

If the servlet is eventually another ZUML page, the page will be added to the current desktop in the rendering phase.

There are two ways to pass parameters to the included page. First, you can use the query string:

 <code><include src="/WEB-INF/mypage?arg=something"/></code>
 

Second, since ZK 3.0.4, you can use DynamicPropertied.setDynamicProperty(java.lang.String, java.lang.Object), or, in ZUL,

 <code><include src="/WEB-INF/mypage" arg="something"/></code>
 

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

1. Include could include anything include ZUML, JSP or any other servlet, while a macro component could embed only a ZUML page.
2. If Include includes a ZUML page, a Page instance is created as a child of 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 creates components in the Rendering phase, while a macro component creates components in HtmlMacroComponent.afterCompose().
4. Component.invalidate() 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:

...

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

boolean	getProgressing() Returns whether to show the MZul.PLEASE_WAIT message before a long operation.
java.lang.String	getSrc() Returns the src.
void	onEchoInclude() Internal use only.
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, getAttributes, getAttributes, getChildren, getDefinition, getDesktop, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, insertBefore, invalidate, isChildable, isInvalidated, isListenerAvailable, isVisible, redraw, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, unsetVariable

Methods inherited from interface org.zkoss.zk.ui.ext.DynamicPropertied

getDynamicProperty, hasDynamicProperty, setDynamicProperty

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, boolean) 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.

onEchoInclude

void onEchoInclude()

Internal use only.

getSrc

java.lang.String getSrc()

Returns the src.

Default: null.

setSrc

void setSrc(java.lang.String src)
            throws WrongValueException

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.

Throws:

WrongValueException

See Also:

DynamicPropertied.setDynamicProperty(java.lang.String, java.lang.Object)