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

Question

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.

I'm not sure if I understand your concrete problem. So I'd say, yes you're crazy :) — BalusC, May 28 '12 at 12:00
@BalusC I may indeed be crazy, but I'm not stating a concrete problem, just a general principle. I've been trying to figure out what actual difference exists between these two constructs and I can't find any. Possibly ui:include doesn't support ui:define, I've been having other problems while testing that. — user207421, May 28 '12 at 21:27
@BalusC If there is one ;-) I understand that ui:decorate is conceptually 'for' templates rather than include files but in terms of implementation it seems to me to be exactly the same thing. — user207421, May 28 '12 at 22:53
The `ui:include` doesn't have the template overhead and is therefore theoretically more efficient if all you need is "just" an include. — BalusC, May 28 '12 at 22:54
@BalusC What template overhead? ui:include understands ui:param so it does at least have some of it. — user207421, May 28 '12 at 22:55
The `` just set an alias in the EL scope. Not much to do with templating. — BalusC, May 28 '12 at 23:01

score 55 · Accepted Answer · edited May 23 '17 at 12:02

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?

I don't understand the difference between 'user-defined template components' and 'existing and pre-defined template'. — user207421, May 28 '12 at 23:27
In the given `/page.xhtml` example, the `` is where the enduser can define variable template components. — BalusC, May 28 '12 at 23:29
I understand that part, I just don't understand the distinction you are drawing. — user207421, May 28 '12 at 23:37
It isn't possible to change the page fragment which is included by `` using ``/``. — BalusC, May 28 '12 at 23:41
@BalusC that shed some light - what about - it seems to not behave the same like ui:include and ui:decorate - what is the trick about this one? — Toskan, Aug 27 '12 at 12:33
@Toskan: The `` ignores anything outside the tag. See also http://stackoverflow.com/questions/4792862/how-to-include-another-xhtml-in-xhtml-using-jsf-2-0-facelets/4793959#4793959 and http://stackoverflow.com/questions/10504190/is-there-a-way-to-run-a-jsf-page-without-building-the-whole-project/10504830#10504830 — BalusC, Aug 27 '12 at 12:40

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

1 Answers1

Linked