org.zkoss.zk.ui
Class HtmlMacroComponent

java.lang.Object
  extended by org.zkoss.zk.ui.AbstractComponent
      extended by org.zkoss.zk.ui.HtmlBasedComponent
          extended by org.zkoss.zk.ui.HtmlMacroComponent
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, Component, AfterCompose, DynamicPropertied, Macro, Scope, IdSpace, ComponentCtrl

public class HtmlMacroComponent
extends HtmlBasedComponent
implements Macro

The implemetation of a macro component for HTML-based clients.

Generally, a macro component is created automatically by ZK loader. If a developer wants to create it manually, it has to instantiate from the correct class, and then invoke afterCompose().

To do additional application-specific tasks, you could override compose(). Both afterCompose() and recreate() depends on compose().

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>
 

Author:
tomyeh
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class org.zkoss.zk.ui.HtmlBasedComponent
HtmlBasedComponent.ExtraCtrl
 
Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent
AbstractComponent.Children
 
Field Summary
protected  java.util.List<VariableResolver> _resolvers
          A list of resolvers (never null).
 
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
 
Constructor Summary
HtmlMacroComponent()
           
 
Method Summary
 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.lang.Object getDynamicProperty(java.lang.String name)
          Returns the property value of the specified name.
 java.lang.String getEnclosingTag()
          Returns the name of the enclosing tag for this macro component.
 java.lang.String getMacroURI()
          Returns the macro URI.
 java.lang.String getWidgetClass()
          Returns the component class (aka., widget type), "zk.Macro".
 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 by use of compose().
protected  void renderProperties(ContentRenderer renderer)
          Renders the content of this component, excluding the enclosing tags and children.
 void setDynamicProperty(java.lang.String name, java.lang.Object value)
          Sets a property with the specified name and value.
 void setEnclosingTag(java.lang.String tag)
          Sets the the name of the enclosing tag for this macro component.
 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.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, detach, 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, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, 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, setPageBefore, 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 class java.lang.Object
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, getAttribute, getAttributes, hasAttribute, hasAttribute, removeAttribute, removeAttribute, removeScopeListener, setAttribute, 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

HtmlMacroComponent

public HtmlMacroComponent()
Method Detail

getWidgetClass

public java.lang.String getWidgetClass()
Returns the component class (aka., widget type), "zk.Macro".

Specified by:
getWidgetClass in interface Component
Overrides:
getWidgetClass in class AbstractComponent
Since:
5.0.0
See Also:
Component.setWidgetClass(java.lang.String)

getEnclosingTag

public java.lang.String getEnclosingTag()
Returns the name of the enclosing tag for this macro component.

Default: span

Since:
5.0.3

setEnclosingTag

public void setEnclosingTag(java.lang.String tag)
Sets the the name of the enclosing tag for this macro component.

Default: span

Since:
5.0.3

afterCompose

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

If a macro component is created by ZK loader, this method is invoked automatically. Developers rarely need to invoke this method.

Default: it invokes compose() to compose the macro component.

Instead of overriding this method, it is suggested to override compose(), since all other methods depend on compose() (rather than afterCompose()).

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().

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

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

By default, supports auto forward events and wire accessible variables to this component.

Since:
5.0.5

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

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.

recreate

public void recreate()
Detaches all child components and then recreate them by use of compose().

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, compose() 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, compose() 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

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 HtmlBasedComponent
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

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

renderProperties

protected void renderProperties(ContentRenderer renderer)
                         throws java.io.IOException
Description copied from class: HtmlBasedComponent
Renders the content of this component, excluding the enclosing tags and children.

See also ZK Client-side Reference: Property Rendering

Overrides:
renderProperties in class HtmlBasedComponent
Throws:
java.io.IOException


Copyright © 2005-2011 Potix Corporation. All Rights Reserved. SourceForge.net Logo