[Myfaces Wiki] Update of "Creating Composite Components" by MikeKienenberger

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Myfaces Wiki" for change notification.

The following page has been changed by MikeKienenberger:
http://wiki.apache.org/myfaces/Creating_Composite_Components

The comment on the change is:
First draft of "Creating Composite Components"

New page:
##language:en
== Overview ==

There are several ways to create composite components

 1.  Programmically create a set of controls as a new component in java code.
 2.  Use Tomahawk t:aliasBean and a jsp include to represent your composite control.
 3.  Use facelets ui:include and ui:composition to represent your composite control.
 4.  Use the Shale/Clay library.

The resulting code for t:aliasBean and ui:include are very similar, and converting
from t:aliasBean to ui:include is trivial in most cases.  The reverse is also trivial provided only one backing bean parameter is specified.

=== Programmically ===

Programmically creating a set of controls as a new component in java code is the hardest, most involved, and most fragile way to do it.  Note that you want to do parent.getChildren().add(child) rather than setParent(parent) to attach children.

It's often useful to add an empty h:panelGroup component to your page, bind the panelGroup to your backing bean that's building the component, and create the component as child of the panelGroup.

{{{
public createComponent()
{
private UIComponent panelGroup;
public void setPanelGroup(UIComponent panelGroup) { this.panelGroup = panelGroup; }
public UIComponent setPanelGroup) { return this.panelGroup; }

public createComponent() {
    UIOutput label = new UIOutput();
    label.setValue("Username:");

    UIInput username = new UIInput();
    username.setId("username");
    username.setValueBinding("value", ...);

    panelGroup.getChildren().add(label);
    panelGroup.getChildren().add(username);
}
}}} 

=== Tomahawk t:aliasBean and a jsp include ===

Using a t:aliasBean and a jsp include is easy and requires only a dependency on t:aliasBean.   There may be some issues with nesting t:aliasBean controls, however.  You're also limited to passing a single backing bean parameter

{{{
<t:aliasBean alias="#{localBackingBean}" value="#{thisInstanceBackingBean}">
    <f:subview>
        <jsp:include page="/pages/BooleanRelationshipDataTable.jsp"/>
    </f:subview>
</t:aliasBean>
}}}

{{{
<!-- /pages/BooleanRelationshipDataTable.jsp -->
<t:dataTable value="#{localBackingBean}" ... >
}}} 

=== facelets ui:include and ui:composition ===

Using a facelets ui:include and ui:composition is also easy and requires a dependency on the facelets library.

{{{
<ui:include src="/WEB-INF/siteNav.xhtml">
    <ui:param name="user" value="#{currentUser}"/>
    <ui:param name="page" value="home"/>
</ui:include>
}}} 
{{{
<!-- /WEB-INF/siteNav.xhtml-->
<ui:composition>
    <h:outputText value="#{page}"/>
    <h:outputText value="#{user}"/>
</ui:composition>
}}} 


=== Shale Clay ===
[TBA]

=== Other examples ===

 * Programmically with java code
  * The custom control tutorial on the exadel website
  * Kito D. Manns book JSF in action
  * You can find an example of a composite dataTable/button/column/columns/checkbox in issue MYFACES-331: http://issues.apache.org/jira/secure/attachment/12311217/RowAndColumnRelationshipComponent.zip

 * Clay
  * You can find a good clay example in the "roledex" usecase.

 * Facelets
  * http://hookom.blogspot.com/2005/05/facelets-templating.html

=== Credits ===

This topic was compiled from posts by 
 * Jacob Hookom
 * Mike Kienenberger
 * Craig !McClanahan
 * Werner Punz
 * Gary !VanMatre