org.zkoss.zml
Class XmlMacroComponent

java.lang.Object
  extended by org.zkoss.zk.ui.AbstractComponent
      extended by 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.


        
                org.zkoss.zk.ui.macro.autowire.convention
                true
        
 

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


        
                org.zkoss.zk.ui.macro.autowire.disabled
                true
        
 

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
 
Field Summary
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
CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE
 
Constructor Summary
XmlMacroComponent()
           
 
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 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, 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, getExtraCtrl, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getStubonly, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, onWrongValue, query, queryAll, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, removeScopeListener, render, render, render, renderProperties, replace, response, response, response, service, 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

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

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


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