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

by

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?

More Related Contents:

  1. JSTL in JSF2 Facelets… makes sense?
  2. JSF returns blank/unparsed page with plain/raw XHTML/XML/EL source instead of rendered HTML output
  3. How to include another XHTML in XHTML using JSF 2.0 Facelets?
  4. How to reference CSS / JS / image resource in Facelets template?
  5. How to ajax-refresh dynamic include content by navigation menu? (JSF SPA)
  6. Sometimes I see JSF URL is *.jsf, sometimes *.xhtml and sometimes /faces/*. Why?
  7. Why do I need to nest a component with rendered=”#{some}” in another component when I want to ajax-update it?
  8. How to send form input values and invoke a method in JSF bean
  9. How to create dynamic JSF form fields
  10. Obtaining Facelets templates/files from an external filesystem or database
  11. When using templating, where should I declare the ?
  12. Packaging Facelets files (templates, includes, composites) in a JAR
  13. Outcommented Facelets code still invokes EL expressions like #{bean.action()} and causes javax.el.PropertyNotFoundException on #{bean.action}
  14. How can I set id of a component/tag inside ui:repeat
  15. How to create a custom Facelets tag?
  16. Avoiding duplicate ids when reusing facelets compositions in the same naming container
  17. How to implement a dynamic list with a JSF 2.0 Composite Component?
  18. @Inject to pass params to a CDI @Named bean via URL
  19. How to use Facelets composition with files from another context
  20. How to insert special characters like & and < into JSF components' value attribute?
  21. Java EE6> Packaging JSF facelets (xhtml) and ManagedBeans as JAR
  22. How to display my application’s errors in JSF?
  23. Why is the getter called so many times by the rendered attribute?
  24. Reset input fields without executing validation
  25. Why does @PostConstruct callback fire every time even though bean is @ViewScoped? JSF
  26. JSF/Facelets: why is it not a good idea to mix JSF/Facelets with HTML tags?
  27. Does it matter whether place f:event inside f:metadata or not?
  28. Is Facelets page generated to Servlet as JSP generated to Servlet
  29. Facelets and JSTL (Converting a Date to a String for use in a field)
  30. Pass method argument/parameter to composite-component action attribute

Leave a Comment