Reference Manual for Gracelets - 2.0.0.RC2

6.4 - Appendix : Component Reference

To write Facelet tag libraries or JSF components and then tie those components to a tag library in facelets requires alot of scaffolding code and setup. While there are possible advantages for certain scenarios, it is often observed that the benefits of so much configuration and scaffolding code (usually only beneficial for large development teams) are not worth the cost in time and maintenance. In addition, development time due to the need for so much rebuilding and redeployment makes component development very cumbersom and unproductive.

Gracelet Libraries attempt to cut out most, if not all, of the configuration and scaffolding code and get directly to component development. Also, it is very easy to develop components, since hot reloading is enabled. Gracelet Libraries also give you the ability to keep alot of common code right next to each other, such as writing a compact phase listener hook right next to the component, or components, that use it.

Each library must declare a namspace variable, which causes it to automatically be available as a Facelet tag library (no .taglib.xml's to write!).

There are various components that you can easily write in a Gracelet Library as shown in the following list:

Gracelet Library Component Types
Type	Reference
Generic	[Usage Reference]
Graphic	[Usage Reference]
Command	[Usage Reference]
Data	[Usage Reference]
Form	[Usage Reference]
Input	[Usage Reference]
SelectOne	[Usage Reference]
SelectMany	[Usage Reference]
Output	[Usage Reference]
SelectItem	[Usage Reference]
SelectItems	[Usage Reference]
Message	[Usage Reference]
Messages	[Usage Reference]
TagHandler	[Usage Reference]
ComponentHandler	[Usage Reference]
Renderer	[Usage Reference]
Converter	[Usage Reference]
Validator	[Usage Reference]
RenderKit	[Usage Reference]
Phase	[Usage Reference]
ScriptBindings	[Usage Reference]

Below the definition of all these types are some real library examples.

General Information About Libraries and Components

Variable resolution inside the closures is the same as mentioned in the previous section about view scripts.

A gracelet library is detected by the convention of the last part of its name. If a file ending in ComponentLibrary.groovy is found in the WEB-INF/gracelet/lib directory of your web application it will be loaded as a gracelet library. When the source is loaded as a groovy file it is hot loadable. Once you have a library developed but want to cut down on the compilation process needed for .groovy files, you can compile that groovy file as a class. As long as the last part of the class file is ComponentLibrary.class you can put it in any package you want, as long the jar has a seam.properties file, it will be found.

All of the items defined in the library should be assigned to non-declared variables. That means you should not use the 'def' keyword when defining a component of the library or the namespace.

For instance, to define the namespace for your library, you simply do the following:

Toggle Line Numbers

1 
namespace = 'http://mycompany.com/tags'

If you did the following it would not work, since you are declaring the namespace variable:

Toggle Line Numbers

1 
def namespace = 'http://mycompany.com/tags'

Another interesting point is that a library is an application singleton, so if you do define variables locally you can access such in your closures to hold/manage application level/library specific state.

In order to define a component you will use the method defined below for each different type. You simply pass a map of settings to the component in order to participate in component execution. You only have to define the settings that you are interested in specifying.

When the parameter expects a closure, the closure can accept the values mentioned in each reference table below for each type. Thos values are optional, so you do not have to declare that you accept any of them if you do not need them.

As you will notice, most of the closures you can define are passed the gracelet UIComponent instance as the first possible parameter. Each gracelet component has a support class that contians many useful convenience methods for rendering and other such things. You can access the support class via the support property of the component. The following is a list of methods that can be used when accessing the support class:

Method	Purpose
void getActionURL()	Returns the URL needed for post backs, like forms.
void getBuilder()	Returns a new instance of a RendererMarkupBuilder for this component
void renderChildren()	Renders the children components of the Gracelet Component
String renderChildrenAsText()	Renders the children components and returns them as a string
void renderComponent(UIComponent,FacesContext)	Renders the specified component
void renderComponents(Class)	Renders the children of this component that are of the class passed or a sub class
String renderComponentsAsText(Collection)	Renders the collection of components passed
void renderFacet(String)	Renders the facet referenced by the name passed.
UIComponent findParent(Class<? extends UIComponent>)	Finds the first ancestor parent of this component that is of the type specified by the class
UIComponent findParent(UIComponent,Class<? extends UIComponent>)	The same as the previous method, but will search for the UIComponent passed

To facilitate definition, most components will allow you to specify an unnamed closure as the last parameter passed. The closure marked in this color is the one that will be the default closure to be defined in these cases.

Library Component - Generic

To create a component of this type in a Gracelet Library, you use the Generic() method.

Generic components extend the UIComponentBase, and thus are truly generic. You can use them when there is no other component type that fits your purpose.

Setting Name	Possible Parameters
rendersChildren	Boolean
broadcast	{ GraceletGenericComponent,FacesEvent -> ... }
getClientId	{ GraceletGenericComponent,FacesContext -> ... }
encodeBegin	{ GraceletGenericComponent,FacesContext -> ... }
encodeChildren	{ GraceletGenericComponent,FacesContext -> ... }
encodeEnd	{ GraceletGenericComponent,FacesContext -> ... }
processDecodes	{ GraceletGenericComponent,FacesContext -> ... }
processUpdates	{ GraceletGenericComponent,FacesContext -> ... }
processValidators	{ GraceletGenericComponent,FacesContext -> ... }
queue	{ GraceletGenericComponent,FacesEvent -> ... }
setValueExpression	{ GraceletGenericComponent,String,ValueExpression -> ... }
getValueExpresson	{ GraceletGenericComponent,String -> ... }
decoder	{ GraceletGenericComponent,FacesContext -> ... }
getFacesListener	{ GraceletGenericComponent,Class -> ... }
addFacesListener	{ GraceletGenericComponent,FacesListener -> ... }
removeFacesListener	{ GraceletGenericComponent,FacesListener -> ... }
isRendered	{ GraceletGenericComponent -> ... }
getContainerClientId	{ GraceletGenericComponent,FacesContext -> ... }

Library Component - Graphic

To create a component of this type in a Gracelet Library, you use the Graphic() method.

Generic components extend the UIComponentBase, and thus are truly generic. You can use them when there is no other component type that fits your purpose.

Setting Name	Possible Parameters
rendersChildren	Boolean
broadcast	{ GraceletGenericComponent,FacesEvent -> ... }
getClientId	{ GraceletGenericComponent,FacesContext -> ... }
encodeBegin	{ GraceletGenericComponent,FacesContext -> ... }
encodeChildren	{ GraceletGenericComponent,FacesContext -> ... }
encodeEnd	{ GraceletGenericComponent,FacesContext -> ... }
processDecodes	{ GraceletGenericComponent,FacesContext -> ... }
processUpdates	{ GraceletGenericComponent,FacesContext -> ... }
processValidators	{ GraceletGenericComponent,FacesContext -> ... }
queue	{ GraceletGenericComponent,FacesEvent -> ... }
setValueExpression	{ GraceletGenericComponent,String,ValueExpression -> ... }
getValueExpresson	{ GraceletGenericComponent,String -> ... }
decoder	{ GraceletGenericComponent,FacesContext -> ... }
getFacesListener	{ GraceletGenericComponent,Class -> ... }
addFacesListener	{ GraceletGenericComponent,FacesListener -> ... }
removeFacesListener	{ GraceletGenericComponent,FacesListener -> ... }
isRendered	{ GraceletGenericComponent -> ... }
getContainerClientId	{ GraceletGenericComponent,FacesContext -> ... }
getValue	{ GraceletGenericComponent -> ... }
setValue	{ GraceletGenericComponent,Object -> ... }
getUrl	{ GraceletGenericComponent -> ... }
setUrl	{ GraceletGenericComponent,String -> ... }

Library Component - Command

To create a component of this type in a Gracelet Library, you use the Command() method.

Command components extend the UICommand class, and thus are true command objects recognized by the JSF system. You will need to take care of post back recognition and event queueing in order for the action expression and listeners to be called.

Setting Name	Possible Parameters
rendersChildren	Boolean
broadcast	{ GraceletCommandComponent,FacesEvent -> ... }
getClientId	{ GraceletCommandComponent,FacesContext -> ... }
encodeBegin	{ GraceletCommandComponent,FacesContext -> ... }
encodeChildren	{ GraceletCommandComponent,FacesContext -> ... }
encodeEnd	{ GraceletCommandComponent,FacesContext -> ... }
processDecodes	{ GraceletCommandComponent,FacesContext -> ... }
processUpdates	{ GraceletCommandComponent,FacesContext -> ... }
processValidators	{ GraceletCommandComponent,FacesContext -> ... }
queue	{ GraceletCommandComponent,FacesEvent -> ... }
setValueExpression	{ GraceletCommandComponent,String,ValueExpression -> ... }
getValueExpresson	{ GraceletCommandComponent,String -> ... }
decoder	{ GraceletCommandComponent,FacesContext -> ... }
getFacesListener	{ GraceletCommandComponent,Class -> ... }
addFacesListener	{ GraceletCommandComponent,FacesListener -> ... }
removeFacesListener	{ GraceletCommandComponent,FacesListener -> ... }
isRendered	{ GraceletCommandComponent -> ... }
getContainerClientId	{ GraceletCommandComponent,FacesContext -> ... }
getActionExpression	{ GraceletCommandComponent -> ... }
getActionListeners	{ GraceletCommandComponent -> ... }
isImmediate	{ GraceletCommandComponent -> ... }
addActionListener	{ GraceletCommandComponent,ActionListener -> ... }
removeActionListener	{ GraceletCommandComponent,ActionListener -> ... }
setActionExpression	{ GraceletCommandComponent,MethodExpression -> ... }
setImmediate	{ GraceletCommandComponent,Boolean -> ... }
getValue	{ GraceletCommandComponent -> ... }
setValue	{ GraceletCommandComponent,Object -> ... }

Library Component - Data

To create a component of this type in a Gracelet Library, you use the Data() method.

Data components extend the UIData class, and thus are true data objects recognized by the JSF system and will expect DataModel's as their values.

Setting Name	Possible Parameters
rendersChildren	Boolean
broadcast	{ GraceletDataComponent,FacesEvent -> ... }
getClientId	{ GraceletDataComponent,FacesContext -> ... }
encodeBegin	{ GraceletDataComponent,FacesContext -> ... }
encodeChildren	{ GraceletDataComponent,FacesContext -> ... }
encodeEnd	{ GraceletDataComponent,FacesContext -> ... }
processDecodes	{ GraceletDataComponent,FacesContext -> ... }
processUpdates	{ GraceletDataComponent,FacesContext -> ... }
processValidators	{ GraceletDataComponent,FacesContext -> ... }
queue	{ GraceletDataComponent,FacesEvent -> ... }
setValueExpression	{ GraceletDataComponent,String,ValueExpression -> ... }
getValueExpresson	{ GraceletDataComponent,String -> ... }
decoder	{ GraceletDataComponent,FacesContext -> ... }
getFacesListener	{ GraceletDataComponent,Class -> ... }
addFacesListener	{ GraceletDataComponent,FacesListener -> ... }
removeFacesListener	{ GraceletDataComponent,FacesListener -> ... }
isRendered	{ GraceletDataComponent -> ... }
getContainerClientId	{ GraceletDataComponent,FacesContext -> ... }
getDataModel	{ GraceletDataComponent -> ... }
getFirst	{ GraceletDataComponent -> ... }
getFooter	{ GraceletDataComponent -> ... }
getHeader	{ GraceletDataComponent -> ... }
getRowCount	{ GraceletDataComponent -> ... }
getRowData	{ GraceletDataComponent -> ... }
getRowIndex	{ GraceletDataComponent -> ... }
getValue	{ GraceletDataComponent -> ... }
getVar	{ GraceletDataComponent -> ... }
getRowsAvailable	{ GraceletDataComponent -> ... }
setDataModel	{ GraceletDataComponent -> ... }
setFirst	{ GraceletDataComponent -> ... }
setFooter	{ GraceletDataComponent -> ... }
setHeader	{ GraceletDataComponent -> ... }
setRowCount	{ GraceletDataComponent -> ... }
setRowData	{ GraceletDataComponent -> ... }
setRowIndex	{ GraceletDataComponent -> ... }
setValue	{ GraceletDataComponent -> ... }
setVar	{ GraceletDataComponent -> ... }
setRowsAvailable	{ GraceletDataComponent -> ... }

Library Component - Form

To create a component of this type in a Gracelet Library, you use the Form() method.

Form components extend the UIForm class, and thus are truly form components recognized by the JSF system.

Setting Name	Possible Parameters
rendersChildren	Boolean
broadcast	{ GraceletFormComponent,FacesEvent -> ... }
getClientId	{ GraceletFormComponent,FacesContext -> ... }
encodeBegin	{ GraceletFormComponent,FacesContext -> ... }
encodeChildren	{ GraceletFormComponent,FacesContext -> ... }
encodeEnd	{ GraceletFormComponent,FacesContext -> ... }
processDecodes	{ GraceletFormComponent,FacesContext -> ... }
processUpdates	{ GraceletFormComponent,FacesContext -> ... }
processValidators	{ GraceletFormComponent,FacesContext -> ... }
queue	{ GraceletFormComponent,FacesEvent -> ... }
setValueExpression	{ GraceletFormComponent,String,ValueExpression -> ... }
getValueExpresson	{ GraceletFormComponent,String -> ... }
decoder	{ GraceletFormComponent,FacesContext -> ... }
getFacesListener	{ GraceletFormComponent,Class -> ... }
addFacesListener	{ GraceletFormComponent,FacesListener -> ... }
removeFacesListener	{ GraceletFormComponent,FacesListener -> ... }
isRendered	{ GraceletFormComponent -> ... }
getContainerClientId	{ GraceletFormComponent,FacesContext -> ... }
isSubmitted	{ GraceletFormComponent -> ... }

Library Component - Input

To create a component of this type in a Gracelet Library, you use the Input() method.

Input components extend the UIInput class, and thus are truly input components recognized by the JSF system.

Setting Name	Possible Parameters
rendersChildren	Boolean
broadcast	{ GraceletInputComponent,FacesEvent -> ... }
getClientId	{ GraceletInputComponent,FacesContext -> ... }
encodeBegin	{ GraceletInputComponent,FacesContext -> ... }
encodeChildren	{ GraceletInputComponent,FacesContext -> ... }
encodeEnd	{ GraceletInputComponent,FacesContext -> ... }
processDecodes	{ GraceletInputComponent,FacesContext -> ... }
processUpdates	{ GraceletInputComponent,FacesContext -> ... }
processValidators	{ GraceletInputComponent,FacesContext -> ... }
queue	{ GraceletInputComponent,FacesEvent -> ... }
setValueExpression	{ GraceletInputComponent,String,ValueExpression -> ... }
getValueExpresson	{ GraceletInputComponent,String -> ... }
decoder	{ GraceletInputComponent,FacesContext -> ... }
getFacesListener	{ GraceletInputComponent,Class -> ... }
addFacesListener	{ GraceletInputComponent,FacesListener -> ... }
removeFacesListener	{ GraceletInputComponent,FacesListener -> ... }
isRendered	{ GraceletInputComponent -> ... }
getContainerClientId	{ GraceletInputComponent,FacesContext -> ... }
getConverter	{ GraceletInputComponent -> ... }
getLocalValue	{ GraceletInputComponent -> ... }
setConverter	{ GraceletInputComponent,Converter -> ... }
addValidator	{ GraceletInputComponent,Validator -> ... }
removeValidator	{ GraceletInputComponent,Validator -> ... }
addValueChangeListener	{ GraceletInputComponent,ValueChangeListener -> ... }
removeValueChangeListener	{ GraceletInputComponent,ValueChangeListener -> ... }
compareValues	{ GraceletInputComponent,Object,Object -> ... }
getConvertedValue	{ GraceletInputComponent,FacesContext,Object -> ... }
getConverterMessage	{ GraceletInputComponent -> ... }
getRequiredMessage	{ GraceletInputComponent -> ... }
getSubmittedValue	{ GraceletInputComponent -> ... }
getValidatorMessage	{ GraceletInputComponent -> ... }
getValidators	{ GraceletInputComponent -> ... }
getValueChangeListeners	{ GraceletInputComponent -> ... }
isLocalValueSet	{ GraceletInputComponent -> ... }
isRequired	{ GraceletInputComponent -> ... }
isValid	{ GraceletInputComponent -> ... }
resetValue	{ GraceletInputComponent -> ... }
setConverterMessage	{ GraceletInputComponent,String -> ... }
setLocalValueSet	{ GraceletInputComponent,Boolean -> ... }
setRequired	{ GraceletInputComponent,Boolean -> ... }
setRequiredMessage	{ GraceletInputComponent,String -> ... }
setSubmittedValue	{ GraceletInputComponent,Boolean -> ... }
setValid	{ GraceletInputComponent,Boolean -> ... }
setValidatorMessge	{ GraceletInputComponent,String -> ... }
updateModel	{ GraceletInputComponent,FacesContext -> ... }
validate	{ GraceletInputComponent,FacesContext -> ... }
validateValue	{ GraceletInputComponent,FacesContext,Object -> ... }
isImmediate	{ GraceletInputComponent -> ... }
setImmediate	{ GraceletInputComponent,Boolean -> ... }
getValue	{ GraceletInputComponent -> ... }
setValue	{ GraceletInputComponent,Object -> ... }

Library Component - SelectOne

To create a component of this type in a Gracelet Library, you use the SelectOne() method.

SelectOne components extend the UISelectOne class, and thus are truly single selection components recognized by the JSF system.

Setting Name	Possible Parameters
rendersChildren	Boolean
broadcast	{ GraceletInputComponent,FacesEvent -> ... }
getClientId	{ GraceletInputComponent,FacesContext -> ... }
encodeBegin	{ GraceletInputComponent,FacesContext -> ... }
encodeChildren	{ GraceletInputComponent,FacesContext -> ... }
encodeEnd	{ GraceletInputComponent,FacesContext -> ... }
processDecodes	{ GraceletInputComponent,FacesContext -> ... }
processUpdates	{ GraceletInputComponent,FacesContext -> ... }
processValidators	{ GraceletInputComponent,FacesContext -> ... }
queue	{ GraceletInputComponent,FacesEvent -> ... }
setValueExpression	{ GraceletInputComponent,String,ValueExpression -> ... }
getValueExpresson	{ GraceletInputComponent,String -> ... }
decoder	{ GraceletInputComponent,FacesContext -> ... }
getFacesListener	{ GraceletInputComponent,Class -> ... }
addFacesListener	{ GraceletInputComponent,FacesListener -> ... }
removeFacesListener	{ GraceletInputComponent,FacesListener -> ... }
isRendered	{ GraceletInputComponent -> ... }
getContainerClientId	{ GraceletInputComponent,FacesContext -> ... }
getConverter	{ GraceletInputComponent -> ... }
getLocalValue	{ GraceletInputComponent -> ... }
setConverter	{ GraceletInputComponent,Converter -> ... }
addValidator	{ GraceletInputComponent,Validator -> ... }
removeValidator	{ GraceletInputComponent,Validator -> ... }
addValueChangeListener	{ GraceletInputComponent,ValueChangeListener -> ... }
removeValueChangeListener	{ GraceletInputComponent,ValueChangeListener -> ... }
compareValues	{ GraceletInputComponent,Object,Object -> ... }
getConvertedValue	{ GraceletInputComponent,FacesContext,Object -> ... }
getConverterMessage	{ GraceletInputComponent -> ... }
getRequiredMessage	{ GraceletInputComponent -> ... }
getSubmittedValue	{ GraceletInputComponent -> ... }
getValidatorMessage	{ GraceletInputComponent -> ... }
getValidators	{ GraceletInputComponent -> ... }
getValueChangeListeners	{ GraceletInputComponent -> ... }
isLocalValueSet	{ GraceletInputComponent -> ... }
isRequired	{ GraceletInputComponent -> ... }
isValid	{ GraceletInputComponent -> ... }
resetValue	{ GraceletInputComponent -> ... }
setConverterMessage	{ GraceletInputComponent,String -> ... }
setLocalValueSet	{ GraceletInputComponent,Boolean -> ... }
setRequired	{ GraceletInputComponent,Boolean -> ... }
setRequiredMessage	{ GraceletInputComponent,String -> ... }
setSubmittedValue	{ GraceletInputComponent,Boolean -> ... }
setValid	{ GraceletInputComponent,Boolean -> ... }
setValidatorMessge	{ GraceletInputComponent,String -> ... }
updateModel	{ GraceletInputComponent,FacesContext -> ... }
validate	{ GraceletInputComponent,FacesContext -> ... }
validateValue	{ GraceletInputComponent,FacesContext,Object -> ... }
isImmediate	{ GraceletInputComponent -> ... }
setImmediate	{ GraceletInputComponent,Boolean -> ... }
getValue	{ GraceletInputComponent -> ... }
setValue	{ GraceletInputComponent,Object -> ... }

Library Component - SelectMany

To create a component of this type in a Gracelet Library, you use the SelectMany() method.

SelectOne components extend the UISelectOne class, and thus are truly single selection components recognized by the JSF system.

Setting Name	Possible Parameters
rendersChildren	Boolean
broadcast	{ GraceletInputComponent,FacesEvent -> ... }
getClientId	{ GraceletInputComponent,FacesContext -> ... }
encodeBegin	{ GraceletInputComponent,FacesContext -> ... }
encodeChildren	{ GraceletInputComponent,FacesContext -> ... }
encodeEnd	{ GraceletInputComponent,FacesContext -> ... }
processDecodes	{ GraceletInputComponent,FacesContext -> ... }
processUpdates	{ GraceletInputComponent,FacesContext -> ... }
processValidators	{ GraceletInputComponent,FacesContext -> ... }
queue	{ GraceletInputComponent,FacesEvent -> ... }
setValueExpression	{ GraceletInputComponent,String,ValueExpression -> ... }
getValueExpresson	{ GraceletInputComponent,String -> ... }
decoder	{ GraceletInputComponent,FacesContext -> ... }
getFacesListener	{ GraceletInputComponent,Class -> ... }
addFacesListener	{ GraceletInputComponent,FacesListener -> ... }
removeFacesListener	{ GraceletInputComponent,FacesListener -> ... }
isRendered	{ GraceletInputComponent -> ... }
getContainerClientId	{ GraceletInputComponent,FacesContext -> ... }
getConverter	{ GraceletInputComponent -> ... }
getLocalValue	{ GraceletInputComponent -> ... }
setConverter	{ GraceletInputComponent,Converter -> ... }
addValidator	{ GraceletInputComponent,Validator -> ... }
removeValidator	{ GraceletInputComponent,Validator -> ... }
addValueChangeListener	{ GraceletInputComponent,ValueChangeListener -> ... }
removeValueChangeListener	{ GraceletInputComponent,ValueChangeListener -> ... }
compareValues	{ GraceletInputComponent,Object,Object -> ... }
getConvertedValue	{ GraceletInputComponent,FacesContext,Object -> ... }
getConverterMessage	{ GraceletInputComponent -> ... }
getRequiredMessage	{ GraceletInputComponent -> ... }
getSubmittedValue	{ GraceletInputComponent -> ... }
getValidatorMessage	{ GraceletInputComponent -> ... }
getValidators	{ GraceletInputComponent -> ... }
getValueChangeListeners	{ GraceletInputComponent -> ... }
isLocalValueSet	{ GraceletInputComponent -> ... }
isRequired	{ GraceletInputComponent -> ... }
isValid	{ GraceletInputComponent -> ... }
resetValue	{ GraceletInputComponent -> ... }
setConverterMessage	{ GraceletInputComponent,String -> ... }
setLocalValueSet	{ GraceletInputComponent,Boolean -> ... }
setRequired	{ GraceletInputComponent,Boolean -> ... }
setRequiredMessage	{ GraceletInputComponent,String -> ... }
setSubmittedValue	{ GraceletInputComponent,Boolean -> ... }
setValid	{ GraceletInputComponent,Boolean -> ... }
setValidatorMessge	{ GraceletInputComponent,String -> ... }
updateModel	{ GraceletInputComponent,FacesContext -> ... }
validate	{ GraceletInputComponent,FacesContext -> ... }
validateValue	{ GraceletInputComponent,FacesContext,Object -> ... }
isImmediate	{ GraceletInputComponent -> ... }
setImmediate	{ GraceletInputComponent,Boolean -> ... }
getValue	{ GraceletInputComponent -> ... }
setValue	{ GraceletInputComponent,Object -> ... }
getSelectedValues	{ GraceletInputComponent -> ... }
setSelectedValues	{ GraceletInputComponent,Object[] -> ... }

Library Component - Output

To create a component of this type in a Gracelet Library, you use the Output() method.

Output components extend the UIOutput class, and thus are truly output components recognized by the JSF system.

Setting Name	Possible Parameters
rendersChildren	Boolean
broadcast	{ GraceletGenericComponent,FacesEvent -> ... }
getClientId	{ GraceletGenericComponent,FacesContext -> ... }
encodeBegin	{ GraceletGenericComponent,FacesContext -> ... }
encodeChildren	{ GraceletGenericComponent,FacesContext -> ... }
encodeEnd	{ GraceletGenericComponent,FacesContext -> ... }
processDecodes	{ GraceletGenericComponent,FacesContext -> ... }
processUpdates	{ GraceletGenericComponent,FacesContext -> ... }
processValidators	{ GraceletGenericComponent,FacesContext -> ... }
queue	{ GraceletGenericComponent,FacesEvent -> ... }
setValueExpression	{ GraceletGenericComponent,String,ValueExpression -> ... }
getValueExpresson	{ GraceletGenericComponent,String -> ... }
decoder	{ GraceletGenericComponent,FacesContext -> ... }
getFacesListener	{ GraceletGenericComponent,Class -> ... }
addFacesListener	{ GraceletGenericComponent,FacesListener -> ... }
removeFacesListener	{ GraceletGenericComponent,FacesListener -> ... }
isRendered	{ GraceletGenericComponent -> ... }
getContainerClientId	{ GraceletGenericComponent,FacesContext -> ... }
getConverter	{ GraceletGenericComponent -> ... }
setConverter	{ GraceletGenericComponent,Converter -> ... }
getLocalValue	{ GraceletGenericComponent -> ... }
getValue	{ GraceletGenericComponent -> ... }
setValue	{ GraceletGenericComponent,Object -> ... }

Library Component - SelectItem

To create a component of this type in a Gracelet Library, you use the SelectItem() method.

SelectItem components extend the UISelectItem, and thus are truly selected item components recognized by the JSF system.

Setting Name	Possible Parameters
rendersChildren	Boolean
broadcast	{ GraceletSelectItemComponent,FacesEvent -> ... }
getClientId	{ GraceletSelectItemComponent,FacesContext -> ... }
encodeBegin	{ GraceletSelectItemComponent,FacesContext -> ... }
encodeChildren	{ GraceletSelectItemComponent,FacesContext -> ... }
encodeEnd	{ GraceletSelectItemComponent,FacesContext -> ... }
processDecodes	{ GraceletSelectItemComponent,FacesContext -> ... }
processUpdates	{ GraceletSelectItemComponent,FacesContext -> ... }
processValidators	{ GraceletSelectItemComponent,FacesContext -> ... }
queue	{ GraceletSelectItemComponent,FacesEvent -> ... }
setValueExpression	{ GraceletSelectItemComponent,String,ValueExpression -> ... }
getValueExpresson	{ GraceletSelectItemComponent,String -> ... }
decoder	{ GraceletSelectItemComponent,FacesContext -> ... }
getFacesListener	{ GraceletSelectItemComponent,Class -> ... }
addFacesListener	{ GraceletSelectItemComponent,FacesListener -> ... }
removeFacesListener	{ GraceletSelectItemComponent,FacesListener -> ... }
isRendered	{ GraceletSelectItemComponent -> ... }
getContainerClientId	{ GraceletSelectItemComponent,FacesContext -> ... }
getItemLabel	{ GraceletSelectItemComponent -> ... }
getItemValue	{ GraceletSelectItemComponent -> ... }
getValue	{ GraceletSelectItemComponent -> ... }
isItemDisabled	{ GraceletSelectItemComponent -> ... }
isItemEscaped	{ GraceletSelectItemComponent -> ... }
setItemDescription	{ GraceletSelectItemComponent,String -> ... }
setItemDisabled	{ GraceletSelectItemComponent,Boolean -> ... }
setItemEscaped	{ GraceletSelectItemComponent,Boolean -> ... }
setItemLabel	{ GraceletSelectItemComponent,String -> ... }
setItemValue	{ GraceletSelectItemComponent,Object -> ... }
setValue	{ GraceletSelectItemComponent,Object -> ... }

Library Component - SelectItems

To create a component of this type in a Gracelet Library, you use the SelectItems() method.

SelectItems components extend the UISelectItems, and thus are truly select item components recognized by the JSF system.

Setting Name	Possible Parameters
rendersChildren	Boolean
broadcast	{ GraceletSelectItemsComponent,FacesEvent -> ... }
getClientId	{ GraceletSelectItemsComponent,FacesContext -> ... }
encodeBegin	{ GraceletSelectItemsComponent,FacesContext -> ... }
encodeChildren	{ GraceletSelectItemsComponent,FacesContext -> ... }
encodeEnd	{ GraceletSelectItemsComponent,FacesContext -> ... }
processDecodes	{ GraceletSelectItemsComponent,FacesContext -> ... }
processUpdates	{ GraceletSelectItemsComponent,FacesContext -> ... }
processValidators	{ GraceletSelectItemsComponent,FacesContext -> ... }
queue	{ GraceletSelectItemsComponent,FacesEvent -> ... }
setValueExpression	{ GraceletSelectItemsComponent,String,ValueExpression -> ... }
getValueExpresson	{ GraceletSelectItemsComponent,String -> ... }
decoder	{ GraceletSelectItemsComponent,FacesContext -> ... }
getFacesListener	{ GraceletSelectItemsComponent,Class -> ... }
addFacesListener	{ GraceletSelectItemsComponent,FacesListener -> ... }
removeFacesListener	{ GraceletSelectItemsComponent,FacesListener -> ... }
isRendered	{ GraceletSelectItemsComponent -> ... }
getContainerClientId	{ GraceletSelectItemsComponent,FacesContext -> ... }
getValue	{ GraceletSelectItemsComponent -> ... }
setValue	{ GraceletSelectItemsComponent,Object -> ... }

Library Component - Message

To create a component of this type in a Gracelet Library, you use the Message() method.

Message components extend the UIMessage class, and thus are truly JSF message components. You can use them for components that will display messages about a particular component.

Setting Name	Possible Parameters
rendersChildren	Boolean
encodeBegin	{ GraceletGenericComponent,FacesContext -> ... }
encodeChildren	{ GraceletGenericComponent,FacesContext -> ... }
encodeEnd	{ GraceletGenericComponent,FacesContext -> ... }

Library Component - Messages

To create a component of this type in a Gracelet Library, you use the Messages() method.

Messages components extend the UIMessages, and thus are truly JSF messages components. You can use them to create components that render JSF messages.

Setting Name	Possible Parameters
rendersChildren	Boolean
encodeBegin	{ GraceletGenericComponent,FacesContext -> ... }
encodeChildren	{ GraceletGenericComponent,FacesContext -> ... }
encodeEnd	{ GraceletGenericComponent,FacesContext -> ... }

Library Component - TagHandler

To create a component of this type in a Gracelet Library, you use the TagHandler() method.

TagHandler components extend the facelet TagHandler class. A map can be accepted by the apply closure as shown below. This contains the following values:

Name	Purpose
state	This is a map that is tied to this handler and can be used to hold state
ctx	This is the current FaceletContext
parent	This is the current UIComponent that the handler should apply to
tag	This is the Facelet Tag object that is associated with this handler
tagAttributes	This is meant to replace the 'attributes', 'attmap' and 'atthtml' below which will be deprecated in the future. This will provide easier and more standard access to facelets tag attributes. See javadoc for the class gracelets.api.library.GraceletTagHandlerAttributes class.
config	This is the Facelet TagConfig object that is associated with this handler
attributes	This is the TagAttributes object associated with this handler
attmap	This is a dynamic map that on each get() of a value will resolve the ValueExpression related to the tag
atthtml	This is a map of retreived values off the attmap that have names specified as valid html attributes names

Setting Name	Possible Parameters
apply	{ Map -> ... }

Library Component - ComponentHandler

To create a component of this type in a Gracelet Library, you use the ComponentHandler() method.

ComponentHandler components extend the facelet ComponentHandler class. This can be used to do meta handling on an already existing component or it can be used to do componentType interchanging, in other words, you could have the handler create different components depending on the parameters or other factors.

Setting Name	Possible Parameters
type	Parameter sets String GraceletLibraryComponentConfig { -> ... }
renderer	Parameter sets String { -> ... }
create	{ FacesContext -> ... }
onCreate	{ UIComponent,UIComponent -> ... }
onPopulate	{ UIComponent,UIComponent -> ... }
createId	{ FacesContext -> ... }
ignoreAll	Boolean
alias	Parameter sets Collection { -> ... }
ignore	Parameter sets Collection { -> ... }
metadata	{ Collection -> ... }
rules	{ Collection -> ... }

Library Component - Renderer

To create a component of this type in a Gracelet Library, you use the Renderer() method.

Renderer components extend the Renderer class, and thus are true renderers. You can set the renderer on all of the JSF Component types and reference the same variable that you defined for the renderer.

One diference with Renderer definitions is that they do not translate to valid tags. Rather you generally assign them directly to a component definition. (see real library examples below)

Setting Name	Possible Parameters
rendersChildren	Boolean
clientIdConverter	{ GraceletGenericComponent,FacesContext -> ... }
encodeBegin	{ GraceletGenericComponent,FacesContext -> ... }
encodeChildren	{ GraceletGenericComponent,FacesContext -> ... }
encodeEnd	{ GraceletGenericComponent,FacesContext -> ... }
decoder	{ GraceletGenericComponent,FacesContext -> ... }
isRendered	{ GraceletGenericComponent -> ... }
valueConverter	{ GraceletGenericComponent,FacesContext -> ... }

Library Component - Converter

To create a component of this type in a Gracelet Library, you use the Converter() method.

Converter components allow a closure or a set of two closures to act as converters for values sent and received to and from web post request, usually for input or output components.

Setting Name	Possible Parameters
toString	{ Closure -> ... }
toValue	{ Closure -> ... }

Library Component - Validator

To create a component of this type in a Gracelet Library, you use the Validator() method.

Validator components allow a closure to act as a validator for the posted and converted value for an input component.

Setting Name	Possible Parameters
validator	{ Closure -> ... }

Library Component - RenderKit

To create a component of this type in a Gracelet Library, you use the RenderKit() method.

RenderKit components extend the GraceletRenderKit class, and thus are true render kit objects recognized by the JSF system. You only need to define the closures that you want to in order to participate in the render kit implementation. NOTE: You can only define ONE render kit per gracelet component library.

In most cases the closure will be passed a default implementation so you can simply call that implementations methods and add your own output/code around what it produces.

Setting Name	Possible Parameters
requestKey	String
isPostBack	{ FacesContext,ResponseStateManager -> ... }
getState	{ FacesContext,String,ResponseStateManager -> ... }
writeState	{ FacesContext,Object,ResponseStateManager -> ... }
cloneWithWriter	{ Writer,ResponseWriter -> ... }
endDocument	{ ResponseWriter -> ... }
endElement	{ String,ResponseWriter -> ... }
flush	{ ResponseWriter -> ... }
getCharacterEncoding	{ ResponseWriter -> ... }
getContentType	{ ResponseWriter -> ... }
startDocument	{ ResponseWriter -> ... }
startElement	{ String,UIComponent,ResponseWriter -> ... }
writeAttribute	{ String,Object,String,ResponseWriter -> ... }
writeComment	{ Object,ResponseWriter -> ... }
writeText	{ char[],int,int,ResponseWriter -> ... }
writeURIAttribute	{ String,Object,String,ResponseWriter -> ... }
write	{ char[],int,int,ResponseWriter -> ... }
close	{ ResponseWriter -> ... }
responseStreamWrite	{ int,OutputStream -> ... }
createResponseStream	{ OutputStream,ResponseStream -> ... }
createResponseWriter	{ Writer,String,String,ResponseWriter -> ... }
getRenderer	{ String,String,Map -> ... }
getResponseStateManager	{ ResponseStateManager -> ... }

Library Component - Phase

To create a component of this type in a Gracelet Library, you use the Phase() method.

Phases are really 'phase hook' objects that get registered with the Gracelet Phase Listener. This allows you to create a "phase listener", per se. You can intercept all parts of the JSF Request lifecycle.

As seen below, you simply pass two parameters to the Phase() method. First the phase you want to participate in, and the second, a closure that is the actual code executed on the desired phase. This closure can take 2 parameters, the first is the phase that is is about to be/or has just executed and the second a boolean, if true it means this is executing before the phase in questin and if false, it means this is executing after the phase has completed.

Library Component - ScriptBindings

To create a component of this type in a Gracelet Library, you use the ScriptBindings() method.

Would you like to have some binding automatically available to gracelet view scripts?

You can accomplish this via the ScriptBindings() method in a gracelet library.

The example below would provide a "pageCompiled" variable for all view scripts, which would return a Date object representing when the page was last compiled. Obviously it is wise to use some base library specific name so as not to conflict with gracelet bound variables and other libraries.

The apply closure must return a Map<String,Object> that will be applied to the binding of each and every view script. The resolve closure will allow lazy initlization, if you want to resolve a variable that has failed all normal resolution methods, your closure will be called with the name as the first parameter, and if you return a non-null value, that value will "stick" for the duration of the binding in question.

Setting Name	Possible Parameters
apply	{ GraceletBinding -> ... }
resolve	{ String,GraceletBinding -> ... }

Examples

The following is a gracelet library that is comes with the gracelets jar:

Toggle Line Numbers

1 
package org.ponder.gracelets.impl.library 
2 
 
3 
import javax.faces.event.ActionEvent 
4 
import javax.faces.component.UIForm 
5 
import javax.faces.component.UIData 
6 
import javax.faces.component.UIColumn 
7 
 
8 
/** 
9 
 * This is part of the standard component library which provides some simple additions to the JSF/Facelets component set. 
10 
 */ 
11 
namespace = "http://gracelets/taglib" 
12 
 
13 
cond = Output { cmp -> if (cmp.get("if", true)) cmp.renderChildren() } 
14 
 
15 
/** 
16 
 * This allows you to include views with a binding instead of a static string, which is a limitation 
17 
 * for the standard Facelets include() tag. 
18 
 *  
19 
 * @param @required [String/Binding] src The view that you want to include 
20 
 */ 
21 
include = TagHandler { ctx -> 
22 
    def value = ctx.attributes.src 
23 
    value = value.literal ? value.value : value.getValue(ctx.ctx) 
24 
    if (value == null) return; 
25 
    ctx.state.src = value 
26 
    u.include(src: value) 
27 
} 
28 
 
29 
buttonRenderer = Renderer( 
30 
    decoder: { cmp, ctx -> 
31 
        String clientId = cmp.getClientId(ctx) 
32 
        if( param[clientId] == clientId ) cmp.queueEvent(new ActionEvent(cmp)) 
33 
    }, 
34 
    encodeChildren: { cmp, ctx -> 
35 
        def x = cmp.builder 
36 
        def f = cmp.findParent(UIForm.class) 
37 
         
38 
        if (f == null) print "Your action buttons must be inside of a form." 
39 
         
40 
        def html = cmp.extractHtmlAttributes() 
41 
         
42 
        String clientId = cmp.getClientId(ctx) 
43 
        String onclick = "this.form['$clientId'].value = '$clientId'; this.form.submit();" 
44 
         
45 
        html.id = "button_$clientId" 
46 
        html.onclick = onclick 
47 
        html.class = cmp.get("styleClass", "") 
48 
         
49 
        x.input(type: "hidden", name: clientId, value: "") 
50 
        x.button(html) { 
51 
            if (cmp.children.size() == 0) print cmp.attributes.value 
52 
            else cmp.renderChildren(); 
53 
        } 
54 
    }, 
55 
    rendersChildren: true 
56 
) 
57 
 
58 
/** 
59 
 * This is a command/action component that allows you to use the html 'button' tag. 
60 
 * Which allows you to put anything as children of the button and thus more fully control 
61 
 * what is displayed on the button. This could be easily used to create like a tool bar 
62 
 * with pure icons and no text for instance. If you do not add any children components you 
63 
 * can simply pass a value to it which will be used as the text for the button. 
64 
 *  
65 
 * @param [String] value The button text if no children are passed 
66 
 * @param [Binding/String] action The action to execute when this button is selected 
67 
 */ 
68 
button = Command(renderer: buttonRenderer) 
69 
 
70 
subpagesRenderer = Renderer { cmp, ctx -> 
71 
    if (cmp.getChildCount() == 0) return; 
72 
    if (param["subPage"] != null) { 
73 
        def ve = cmp.getValueExpression("value"); 
74 
        if (ve != null) ve.setValue(elCtx, param["subPage"]) 
75 
    } 
76 
    def value = cmp.attributes.value 
77 
    if (value == null) cmp.renderComponent(cmp.children[0], ctx) 
78 
    else { 
79 
        for (Object child : cmp.children) { 
80 
            def cp = child.attributes["page"] 
81 
            if (cp == null) cp = child.attributes.id 
82 
            if (cp == null) cp = child.attributes.value 
83 
            if (cp == String.valueOf(value)) { 
84 
                cmp.renderComponent(child, ctx) 
85 
                break 
86 
            } 
87 
        } 
88 
    } 
89 
} 
90 
 
91 
/** 
92 
 * This allows you to easily have a form that automatically propogates the current conversation id. 
93 
 */ 
94 
form = TagHandler { ctx -> 
95 
    def atts = [:] 
96 
    ctx.attributes.each { att -> atts[att.key] = att.value.value } 
97 
    h.form(atts) { 
98 
        xh.input(type: "hidden", value: {  
99 
            conversation.id  
100 
        }, name: "conversationId") 
101 
        u.insert() 
102 
    } 
103 
} 
104 
 
105 
/** 
106 
 * This allows each child/sub component to become a "sub page". It holds state as to the current 
107 
 * sub page via a value/closure binding. Each sub/child component must declare a 'page' attribute 
108 
 * in order to be able to reference the sub page via binding assignment. 
109 
 *  
110 
 * @example General Use Example 
111 
 *  
112 
 * g.subpages(value: Value { somePageNavBinding }) { 
113 
 *  h.outputText(page: "page1") { 
114 
 *      g.form { h.commandButton("Page 2", action: { somePageNavBinding = "page2" }) }       
115 
 *  } 
116 
 *  h.outputText(page: "page2") { 
117 
 *      g.form { h.commandButton("Page 1", action: { somePageNavBinding = "page1" }) } 
118 
 *  } 
119 
 * } 
120 
 */ 
121 
subpages = Output( 
122 
    processDecodes: { cmp, ctx -> 
123 
        if (!cmp.rendered) return 
124 
        if (cmp.getChildCount() == 0) return; 
125 
        def value = cmp.attributes.value 
126 
        if (value == null) cmp.children[0].processDecodes(ctx) 
127 
        else { 
128 
            for (Object child : cmp.children) { 
129 
                def cp = child.attributes["page"] 
130 
                if (cp == null) cp = child.attributes.id 
131 
                if (cp == null) cp = child.attributes.value 
132 
                if (cp == String.valueOf(value)) { child.processDecodes(ctx); break; } 
133 
            } 
134 
        } 
135 
        cmp.decode(ctx) 
136 
    }, 
137 
    processUpdates: { cmp, ctx -> 
138 
        if (!cmp.rendered) return 
139 
        if (cmp.getChildCount() == 0) return; 
140 
        def value = cmp.attributes.value 
141 
        if (value == null) cmp.children[0].processUpdates(ctx) 
142 
        else { 
143 
            for (Object child : cmp.children) { 
144 
                def cp = child.attributes["page"] 
145 
                if (cp == null) cp = child.attributes.id 
146 
                if (cp == null) cp = child.attributes.value 
147 
                if (cp == String.valueOf(value)) { child.processUpdates(ctx); break; } 
148 
            } 
149 
        } 
150 
    }, 
151 
    processValidators: { cmp, ctx -> 
152 
        if (!cmp.rendered) return 
153 
        if (cmp.getChildCount() == 0) return; 
154 
        def value = cmp.attributes.value 
155 
        if (value == null) cmp.children[0].processValidators(ctx) 
156 
        else { 
157 
            for (Object child : cmp.children) { 
158 
                def cp = child.attributes["page"] 
159 
                if (cp == null) cp = child.attributes.id 
160 
                if (cp == null) cp = child.attributes.value 
161 
                if (cp == String.valueOf(value)) { child.processValidators(ctx); break; } 
162 
            } 
163 
        } 
164 
    }, 
165 
    renderer: subpagesRenderer 
166 
) 
167 
 
168 
subpageLink = Output { cmp, ctx -> 
169 
    def page = cmp.attributes.value 
170 
    def x = cmp.builder 
171 
    x.a(href: "$actionURL?subPage=$page") { cmp.renderChildren() } 
172 
}

^{Generated by Gracelets Documentation Generator - 08/27/2009 08:27PM CDT}