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.

Yentai

I'm not sure if I understand your concrete problem. So I'd say, yes you're crazy :) – Durfee

@Durfee 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. – Yentai

Ah you're just asking for the conceptual difference? – Durfee

@Durfee 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. – Yentai

The ui:include doesn't have the template overhead and is therefore theoretically more efficient if all you need is "just" an include. – Durfee

@Durfee What template overhead? ui:include understands ui:param so it does at least have some of it. – Yentai

The <ui:param> just set an alias in the EL scope. Not much to do with templating. – Durfee

Answer 1

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?

Durfee

I don't understand the difference between 'user-defined template components' and 'existing and pre-defined template'. – Yentai

In the given /page.xhtml example, the <ui:define> is where the enduser can define variable template components. – Durfee

I understand that part, I just don't understand the distinction you are drawing. – Yentai

It isn't possible to change the page fragment which is included by <ui:include> using <ui:insert>/<ui:define>. – Durfee

@Durfee that shed some light - what about <ui:composition template="./someTemplate.xhtml"> - it seems to not behave the same like ui:include and ui:decorate - what is the trick about this one? – Yorker

@Toskan: The <ui:composition> ignores anything outside the tag. See also stackoverflow.com/questions/4792862/… and stackoverflow.com/questions/10504190/… – Durfee