What is the real conceptual difference between ui:decorate and ui:include?

facelets, jsf

Solution

The main difference between `<ui:include>` and `<ui:decorate>` is that the `<ui:decorate>` is intended to allow insertion of user-defined template components, while the `<ui:include>` is intended to include an existing and already-predefined template.

This indeed means that the `<ui:decorate>` supports `<ui:define>` for user-defined template components in its body and can insert it at the `<ui:insert>` place inside the template.

Here's a -somewhat clumsy- example to show where it can be used:

`/WEB-INF/templates/field.xhtml`

<ui:composition
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:ui="http://java.sun.com/jsf/facelets"
>
    <h:outputLabel for="#{id}" value="#{label}" />
    <ui:insert name="input" />
    <h:message id="#{id}_message" for="#{id}" />
</ui:composition>

`/page.xhtml`

<h:panelGrid columns="3">
    <ui:decorate template="/WEB-INF/templates/field.xhtml">
        <ui:param name="label" value="Foo" />
        <ui:param name="id" value="foo" />
        <ui:define name="input">
            <h:inputText id="foo" value="#{bean.foo}" required="true" />
        </ui:define>
    </ui:decorate>
    <ui:decorate template="/WEB-INF/templates/field.xhtml">
        <ui:param name="label" value="Bar" />
        <ui:param name="id" value="bar" />
        <ui:define name="input">
            <h:selectBooleanCheckbox id="bar" value="#{bean.bar}" required="true" />
        </ui:define>
    </ui:decorate>
    ...
</h:panelGrid>

Note that it renders the components nicely in each cell of the panel grid. Again, this particular example is pretty clumsy, I'd just have used a tag file instead. Only if it was a larger section, e.g. a whole form whose e.g. its header or footer should be customizable, then an `<ui:decorate>` would have been appropriate.

Another major advantage of `<ui:decorate>` is that it allows you to use a composite component with a template. See also Is it possible to use template with composite component in JSF 2?

Problem

It occurs ago me that `ui:decorate` is functionally the same as `ui:include` except that you can also pass `ui:param` and `ui:define` to the included file. Am I crazy? EDIT : Although in fact you can pass `ui:param` to a `ui:include` file too, it turns out I am already doing it. Maybe you can pass a `ui:define` as well, I will check and edit here.

Original source

Related problems