Package org.zkoss.zml

Class XmlMacroComponent

java.lang.Object

org.zkoss.zk.ui.AbstractComponent

org.zkoss.zml.XmlMacroComponent

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Component, AfterCompose, DynamicPropertied, Macro, Scope, IdSpace, ComponentCtrl

public class XmlMacroComponent
extends AbstractComponent
implements Macro

The implementation of a macro component for XML output.

By default, compose() will wire members by use of Selectors. In other words, it will wire annotated members the same way as SelectorComposer does.

If you prefer to wire the members based on the name convention as GenericForwardComposer does (i.e., backward compatible with ZK 5), you could specify a library property called org.zkoss.zk.ui.macro.autowire.convention to true in WEB-INF/zk.xml as follows.

	<library-property>
		<name>org.zkoss.zk.ui.macro.autowire.convention</name>
		<value>true</value>
	</library-property>
 

If you prefer not to wire at all (neither by-selector nor by-convention), you could specify a library property called org.zkoss.zk.ui.macro.autowire.disabled to true in WEB-INF/zk.xml as follows..

	<library-property>
		<name>org.zkoss.zk.ui.macro.autowire.disabled</name>
		<value>true</value>
	</library-property>
 

Since:

3.0.0

Author:

tomyeh

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

AbstractComponent.Children, AbstractComponent.ForwardInfo, AbstractComponent.TargetInfo

Field Summary

Fields

Modifier and Type	Field	Description
protected java.util.List<VariableResolver>	_resolvers	A list of resolvers (never null).

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

AFTER_CHILD_ADDED, AFTER_CHILD_REMOVED, AFTER_PAGE_ATTACHED, AFTER_PAGE_DETACHED, AFTER_PARENT_CHANGED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

Constructor Summary

Constructors

Constructor	Description
XmlMacroComponent()

Method Summary

Modifier and Type	Method	Description
void	afterCompose()	Creates the child components after apply dynamic properties setDynamicProperty(java.lang.String, java.lang.Object).
java.lang.Object	clone()	Clones the component.
protected void	compose()	Composes the macro component.
java.util.Map<java.lang.String,java.lang.Object>	getDynamicProperties()	Returns all available dynamic properties.
java.lang.Object	getDynamicProperty(java.lang.String name)	Returns the property value of the specified name.
java.lang.String	getMacroURI()	Returns the macro URI.
boolean	hasDynamicProperty(java.lang.String name)	Returns whether a dynamic property is defined.
protected boolean	isChildable()	Returns whether this component can have a child.
boolean	isInline()	Returns whether this is an inline macro.
void	recreate()	Detaches all child components and then recreate them.
void	redraw(java.io.Writer out)	Redraws this component and all its descendants.
void	setDynamicProperty(java.lang.String name, java.lang.Object value)	Sets a property with the specified name and value.
boolean	setInlineParent(Component parent, Component beforeSibling)	Sets the parent to the given one and insert the children of the inline macro right before the given sibling (beforeSibling).
void	setMacroURI(java.lang.String uri)	Sets the macro URI.
void	setPage(Page page)	Changes the page.
void	setParent(Component parent)	Changes the parent.

Methods inherited from class org.zkoss.zk.ui.AbstractComponent

addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, beforeParentChanged, destroyIndexCacheMap, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, disableHostChanged, enableBindingAnnotation, enableHostChanged, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getCallback, getChildren, getClientAttribute, getClientDataAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getExtraCtrl, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getForwards, getId, getIndexCacheMap, getLastChild, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getPropertyAccess, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, initIndexCacheMap, insertBefore, invalidate, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, onParentChanged, onWrongValue, query, queryAll, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, renderProperties, renderPropertiesOnly, replace, response, response, response, service, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setMold, setPageBefore, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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, hasAttribute, removeAttribute, removeScopeListener, setAttribute

Field Detail

_resolvers

protected final java.util.List<VariableResolver> _resolvers

A list of resolvers (never null). A variable resolver is added automatically if VariableResolver was annotated.

Constructor Detail

XmlMacroComponent

public XmlMacroComponent()

Method Detail

afterCompose

public void afterCompose()

Creates the child components after apply dynamic properties setDynamicProperty(java.lang.String, java.lang.Object).

The second invocation is ignored. If you want to recreate child components, use recreate() instead.

If a macro component is created by ZK loader, this method is invoked automatically. Developers need to invoke this method only if they create a macro component manually.

If this is an line macro, this method is invoked automatically if setParent(org.zkoss.zk.ui.Component) or setPage(org.zkoss.zk.ui.Page) called

Specified by:

afterCompose in interface AfterCompose

compose

protected void compose()

Composes the macro component. It is called by afterCompose(), and others to do the rendering based on getMacroURI().

Since:

5.0.5

setMacroURI

public void setMacroURI(java.lang.String uri)

Description copied from interface: Macro

Sets the macro URI. It affects only this component.

Note: this method calls Macro.recreate() automatically if uri is changed.

Specified by:

setMacroURI in interface Macro

Parameters:

uri - the URI of this macro. If null, the default is used.

getMacroURI

public java.lang.String getMacroURI()

Description copied from interface: Macro

Returns the macro URI.

If Macro.setMacroURI(java.lang.String) wasn't called, it returns the URI defined in the macro definition.

Specified by:

getMacroURI in interface Macro

recreate

public void recreate()

Description copied from interface: Macro

Detaches all child components and then recreate them.

It is used if you have assigned new values to dynamic properties and want to re-create child components to reflect the new values. Note: it is convenient but the performance is better if you can manipulate only the child components that need to be changed. Refer to ZK Developer's Reference for details.

Specified by:

recreate in interface Macro

isInline

public boolean isInline()

Description copied from interface: Macro

Returns whether this is an inline macro. The only way to create an inline macro is by use of ComponentDefinition.newInstance(org.zkoss.zk.ui.Page, java.lang.String).

Specified by:

isInline in interface Macro

setParent

public void setParent(Component parent)

Changes the parent.

Note: if this is an inline macro (isInline()), this method actually changes the parent of all components created from the macro URI. In other word, an inline macro behaves like a controller of the components it created. It doesn't belong to any page or parent. Moreover, afterCompose() is called automatically if it is not called (and this is an inline macro).

Specified by:

setParent in interface Component

Overrides:

setParent in class AbstractComponent

setInlineParent

public boolean setInlineParent(Component parent,
                               Component beforeSibling)

Description copied from interface: Macro

Sets the parent to the given one and insert the children of the inline macro right before the given sibling (beforeSibling).

This method is used only internally.

Notice that when AbstractComponent.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) is called to insert an inline macro (Macro.isInline()), the invocation will be forwarded to this method. It is called only Macro.isInline() is true.

Specified by:

setInlineParent in interface Macro

Parameters:

parent - the parent

beforeSibling - a child of the parent that the macro component will be inserted before

Returns:

if it has been added successfully

setPage

public void setPage(Page page)

Changes the page.

Note: if this is an inline macro (isInline()), this method actually changes the page of all components created from the macro URI. In other word, an inline macro behaves like a controller of the components it created. It doesn't belong to any page or parent. Moreover, afterCompose() is called automatically if it is not called (and this is an inline macro).

Specified by:

setPage in interface Component

Overrides:

setPage in class AbstractComponent

See Also:

ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page), ComponentCtrl.onPageDetached(org.zkoss.zk.ui.Page)

isChildable

protected boolean isChildable()

Description copied from class: AbstractComponent

Returns whether this component can have a child.

Default: return true (means it can have children).

Overrides:

isChildable in class AbstractComponent

redraw

public void redraw(java.io.Writer out)
            throws java.io.IOException

Description copied from class: AbstractComponent

Redraws this component and all its descendants.

Default: It uses JsContentRenderer to render all information in JavaScript codes. For devices that don't support JavaScript, it must override this method.

To generate all information, it first invokes AbstractComponent.renderProperties(org.zkoss.zk.ui.sys.ContentRenderer) to render component's properties, and then AbstractComponent.redrawChildren(java.io.Writer) to redraw children (and descendants) (by calling their AbstractComponent.redraw(java.io.Writer)).

If a derived class wants to render more properties, it can override AbstractComponent.renderProperties(org.zkoss.zk.ui.sys.ContentRenderer).

If a derived class renders only a subset of its children (such as paging/cropping), it could override AbstractComponent.redrawChildren(java.io.Writer).

If a deriving class wants to do something before AbstractComponent.renderProperties(org.zkoss.zk.ui.sys.ContentRenderer), it has to override AbstractComponent.redraw(java.io.Writer).

If a deriving class doesn't want to render in JavaScript codes, it has to override AbstractComponent.redraw(java.io.Writer) with the proper implementation of ContentRenderer.

Specified by:

redraw in interface ComponentCtrl

Overrides:

redraw in class AbstractComponent

Throws:

java.io.IOException

clone

public java.lang.Object clone()

Description copied from interface: Component

Clones the component. All of its children and descendants are cloned. Also, ID are preserved.

Specified by:

clone in interface Component

Overrides:

clone in class AbstractComponent

Returns:

the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.

hasDynamicProperty

public boolean hasDynamicProperty(java.lang.String name)

Description copied from interface: DynamicPropertied

Returns whether a dynamic property is defined.

Specified by:

hasDynamicProperty in interface DynamicPropertied

getDynamicProperties

public java.util.Map<java.lang.String,java.lang.Object> getDynamicProperties()

Description copied from interface: DynamicPropertied

Returns all available dynamic properties.

Specified by:

getDynamicProperties in interface DynamicPropertied

getDynamicProperty

public java.lang.Object getDynamicProperty(java.lang.String name)

Description copied from interface: DynamicPropertied

Returns the property value of the specified name.

Specified by:

getDynamicProperty in interface DynamicPropertied

setDynamicProperty

public void setDynamicProperty(java.lang.String name,
                               java.lang.Object value)
                        throws WrongValueException

Description copied from interface: DynamicPropertied

Sets a property with the specified name and value.

If a component supports only String-type values, it could use org.zkoss.lang.Objects.toString() to convert the value to a String instance.

Specified by:

setDynamicProperty in interface DynamicPropertied

Throws:

WrongValueException