When to use <ui:include>, tag files, composite components and/or custom components?

Solution 1:

What is the difference between those approaches?

Facelet templates

Use Facelet templates (as in <ui:composition>, <ui:include> and <ui:decorate>) if you want to split main page layout fragments into reuseable templates. E.g. header, menu, content, footer, etc.

Examples:

• How to include another XHTML in XHTML using JSF 2.0 Facelets?
• What is the real conceptual difference between ui:decorate and ui:include?
• How to customize h:head when using ui:composition template?
• How to change head elements of a page when using ui:composition
• How to ajax-refresh dynamic include content by navigation menu? (JSF SPA)

Facelet tag files

Use Facelet tag files if you want to have a reuseable group of components in order to prevent/minimize code duplication. E.g. a group of label+input+message components. The major difference with composite components is that the output of a Facelet tag file does not represent a single UIComponent and may in some circumstances be the only solution when a composite component doesn't suffice. Generally, having an <ui:include> with one or more <ui:param> which passes a managed bean property (and thus not a hardcoded value) is a signal that the include file can better be a tag file.

Examples:

• How to create a custom Facelets tag?
• How to make a grid of JSF composite component?
• How to create a composite component for a datatable column?
• Primefaces outputLabel for composite component

Composite components

Use composite components if you want to create a single and reuseable custom UIComponent with a single responsibility using pure XML. Such a composite component usually consists of a bunch of existing components and/or HTML and get physically rendered as single component and is supposed to be bound to a single bean property. E.g. a component which represents a single java.time.LocalDate property by 3 dependent <h:selectOneMenu> components representing day, month and year, or a component which combines <p:fileUpload> and <p:imageCropper> into a single <my:uploadAndCropImage> referring a single custom com.example.Image entity as property.

Examples:

• Our Composite Component wiki page
• The BalusC Code: Composite Component with multiple input fields
• Split java.util.Date over two h:inputText fields representing hour and minute with f:convertDateTime
• Select all items in Multiple SelectManyCheckBox with dynamic ids
• Extending JSF commandLink component
• Avoiding duplicate ids when reusing facelets compositions in the same naming container

Custom components

Use a custom component whenever the functionality cannot be achieved with Facelet tag files or composite components, because of the lack of support in the standard/available set of components. Generally when you want a high degree of control and/or customization of the decoding and/or encoding, and also to offer the endusers the possibility to relatively easily extend/override the decoding and/or encoding. Examples can be found over all place in source code of open source component libraries such as PrimeFaces and OmniFaces.

Tag handlers

When you want to control the building of the JSF component tree instead of rendering of the HTML output, then you should use a tag handler instead of a component.

Examples:

• Custom Facelet component in JSF
• How can I access the content of something created with <ui:define> programmatically?
• Conditional render in tagfile depending on whether the attribute is specified or not
• Performing a redirect, when conversion / validation associated with query parameters fails

Example projects

Here are some example projects which utilize all of above mentioned techniques.

• Java EE Kickoff App (templates - includes - tagfiles - composite)
• OmniFaces Showcase (templates - includes - tagfiles - composite)

Could performance differ?

Technically, the performance concern is negligible. The choice should be made based on the concrete functional requirements and the final degree of abstraction, reusability and maintainability of the implementation. Each approach has its own well definied purpose and limitations.

Composite components do however have a significant overhead during building/restoring of the view (specifically: during saving/restoring the view state). And, in older versions of Mojarra, composite components had performance issues with assigning default values, this is already fixed since 2.1.13. Also, Mojarra had a memory leak when a <cc:attribute method-signature> is used for method expressions, basically the entire component tree is re-referenced in HTTP session, this is fixed since 2.1.29 / 2.2.8. The memory leak can be bypassed in older 2.1 versions as below:

<context-param>
    <param-name>com.sun.faces.serializeServerState</param-name>
    <param-value>true</param-value>
</context-param>

Or in older 2.2 versions as below:

<context-param>
    <param-name>javax.faces.SERIALIZE_SERVER_STATE</param-name>
    <param-value>true</param-value>
</context-param>

Still, when you have relatively "a lot of" composite components, and you have javax.faces.STATE_SAVING_METHOD set to client, then the performance will be a pain. Do not abuse composite components if you merely want the basic functionality which is already possible with a simple include file or tag file. Do not use the ease of configuration (read: no *.taglib.xml file needed) as an excuse to prefer composite components over tag files.

When using Mojarra 2.2.10 or older, do not forget to disable the relatively short Facelets refresh period for production mode:

<context-param>
    <param-name>javax.faces.FACELETS_REFRESH_PERIOD</param-name>
    <param-value>-1</param-value>
</context-param>

Do not use this setting for development, otherwise you've to restart the whole server to get changes in Facelets files to be reflected! Mojarra 2.2.11 and newer, and MyFaces already defaults to -1 when javax.faces.PROJECT_STAGE is not set to Development.