<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" 
    "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
    <header>
        <title>Tiles Support</title>
    </header>
    <body>
        <section id="intro">
            <title>Introduction</title>
            <p>
                Often, within your web application there are shared components such as a
                menu bar, banner or header, footer, and copyright. NetUI provides a couple
                of mechanisms to support layout management for assembling presentation pages
                from separate components. First, there are the <a href="tags/template.xml">
                NetUI Template Tags</a>, a simple templating mechanism, defining a
                template page that contains the layout and information you want on each
                page within a site or page flow. The other option is to use the
                <a href="http://struts.apache.org/userGuide/dev_tiles.html">
                Tiles framework</a> support built into NetUI.
            </p>
            <p>
                Support for Tiles is achieved by incorporating the Tiles plugin and providing
                Tiles related "annotations" in the NetUI declarative programming model for
                the page flow "controller" class.
            </p>
            <p>
                The following is a brief description of the annotations and the steps
                required to use the Tiles support in NetUI.
            </p>
        </section>
        <section id="tiles_definitions">
            <title>Declaring Tiles Definitions</title>
            <p>
                First, create your Tiles definitions and the corresponding layout templates.
                Place your Tiles definition configuration file(s) in the WEB-INF directory.
                A Tiles definition file can also be located in the same directory as the page flow
                controller; however, if it is placed locally, you should avoid including it in the
                deployed webapp (or, if you are deploying your web project in place, you should
                add a Servlet Filter to prevent the file from being externally visible).
            </p>
            <p>
                The definitions you declared should use webapp-relative paths to the JSP files
                that will be the template(s) for the layout, using &lt;tiles:insert> tags from
                the tiles tag library, and the common component JSP files such as header,
                footer, menu, etc. used by the templates. The example definition below
                illustrates the use of a template JSP ("/layout/page.jsp") and common
                component files for the header, menu, and footer. The definitions that extend
                "defaultLayout" define the actual content that should be inserted as the
                content of the "body" component in the page.
            </p>
            <p><strong>/WEB-INF/tiles-defs.xml</strong></p>
<source><![CDATA[
<tiles-definitions>
    <definition name="defaultLayout" path="/layout/page.jsp">
        <put name="exampleTitle" value="Tiles" />
        <put name="header"       value="/layout/header.jsp"/>
        <put name="menu"         value="/menu.jsp"/>
        <put name="body"         value="/layout/body.jsp"/>
        <put name="footer"       value="/layout/footer.jsp"/>
    </definition>

    <definition name="flow1" extends="defaultLayout">
        <put name="exampleTitle" value="Tiles - Flow 1" />
        <put name="body"         value="/flow1/index.jsp" />
    </definition>

    <definition name="flow2" extends="defaultLayout">
        <put name="exampleTitle" value="Tiles - Flow 2" />
        <put name="body"         value="/flow2/index.jsp" />
    </definition>
    ...
</tiles-definitions>
]]></source>
            <p>
                To use the definitions in a page flow, add the <code>tilesDefinitionsConfigs</code>
                attribute to your
                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html">
                    <code>@Jpf.Controller</code>
                </a>
                annotation. This attribute takes an array of paths to support the use of multiple
                Tiles-definitions files if desired. The following is an example of how the
                annotation and attribute would be written for a single configuration file
                named "tiles-defs.xml" and located in the WEB-INF directory.
            </p>
<source>@Jpf.Controller(
    tilesDefinitionsConfigs = { "/WEB-INF/tiles-defs.xml" },
    ...
)</source>
        </section>
        <section id="tiles_def_forward">
            <title>Using Tiles Definitions as Forwards in a Page Flow Controller</title>
            <p>
                For any
                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html">
                    <code>@Jpf.Forward</code>
                </a>,
                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SimpleAction.html">
                    <code>@Jpf.SimpleAction</code>
                </a>, or
                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.ConditionalForward.html">
                    <code>@Jpf.ConditionalForward</code>
                </a>
                annotation you've defined in the actions of your controller, you can define
                the Tiles definition for the <code>@Jpf.Forward</code>. Rather than set the
                path attribute for a JSP, you set the attribute, <code>tilesDefinition</code>.
                This value of the attribute should be the name of a Tiles definition. Using
                the definitions defined above, the following is an example of a Forward
                annotation with the <code>tilesDefinition</code>.
            </p>
<source>@Jpf.Action(
    forwards = {
        @Jpf.Forward(
            name = "continue",
            tilesDefinition = "flow2")
    })</source>
            <p>
                Review the <a href="site:netui-samples">NetUI samples</a> for a concrete
                example of using Tiles support to share a common UI component across page flows.
            </p>
        </section>
    </body>
</document>
