blob: 0b1f04c4038b50ee696637960c072ec4a4268d2a [file] [log] [blame]
<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="dev_tiles.html">
<properties>
<author>Cedric Dumoulin</author>
<title>
The Struts User's Guide - Tiles Guide
</title>
</properties>
<body>
<chapter name="Tiles Guide">
<section name="The Tiles Document Assembly Framework">
<p>Tiles builds on the "include" feature provided by the JavaServer Pages
specification to provide a full-featured, robust framework for assembling
presentation pages from component parts. Each part ("Tile") can be
reused as often as needed throughout your application. This reduces the
amount of markup that needs to be maintained and makes it easier to
change the look and feel of a website.
</p>
</section>
<section href="features" name="Overview of Tiles Features">
<ul>
<li>
Screen definitions
<ul>
<li>
Create a screen by assembling <strong><em>Tiles</em></strong>, e.g. header, footer, menu, body
</li>
<li>
Definitions can take place:
<ul>
<li>
in a centralized XML file
</li>
<li>
directly in JSP pages
</li>
<li>
in Struts <code>Action</code>s
</li>
</ul>
</li>
<li>
Definitions provide an inheritance
mechanism: a definition can extend another one
and override some (or all) of its parameters
</li>
</ul>
</li>
<li>
Layouts
<ul>
<li>
Define common page layouts and reuse them across your web site
</li>
<li>
Define menu layouts and pass lists of items and links
</li>
<li>
Define a portal layout, use it by passing list of <strong><em>Tiles</em></strong> (pages) to show
</li>
<li>
Reuse existing layouts, or define your own ones
</li>
</ul>
</li>
<li>
Dynamic page building
<ul>
<li>
Tiles are gathered dynamically during page reload. It is possible to change any attributes: layout, list of Tiles in portal, list of menu items, ...
</li>
</ul>
</li>
<li>
Reuse of <strong><em>Tiles</em></strong>/Components
<ul>
<li>
If well defined, a <strong><em>Tile</em></strong> can be reused in different locations
</li>
<li>
Dynamic attributes are used to parameterize <em><strong>Tiles</strong>
</em>
</li>
<li>
It is possible to define libraries of reusable <em><strong>Tiles</strong>
</em>.
</li>
<li>
Build a page by assembling predefined components, give them appropriate parameters
</li>
</ul>
</li>
<li>
Internationalization (I18N)
<ul>
<li>
It is possible to load different Tiles according to the user's Locale
</li>
<li>
A mechanism similar to Java properties files is used for definition files: you can have one definition file per Locale, the appropriate definition is loaded according to the current Locale
</li>
</ul>
</li>
<li>
Multi-channels
<ul>
<li>
It is possible to load different Tiles according to a key stored e.g. in session context
</li>
<li>
The key could hold e.g. user privileges, browser type, ...
</li>
<li>
A mechanism similar to Java properties files is used for definition files: you can have one definition file per key, the appropriate definition is loaded according to the key
</li>
</ul>
</li>
</ul>
</section>
<section href="setup" name="Enabling your application for Tiles">
<p>
The Tiles framework is bundled with Struts but not enabled by default. To enable Tiles you need to:
</p>
<ul>
<li>
Setup the struts-tiles taglib in your <code>WEB-INF/web.xml</code> file to include the following tag library declaration:
</li>
</ul>
<pre>&lt;taglib&gt;
&lt;taglib-uri&gt;/WEB-INF/struts-tiles.tld&lt;/taglib-uri&gt;
&lt;taglib-location&gt;/WEB-INF/struts-tiles.tld&lt;/taglib-location&gt;
&lt;/taglib&gt;</pre>
<ul>
<li>
At the top of each JSP page that will use the Tiles custom tags, add the following line declaring the Tiles custom tag library for use on the page:
</li>
</ul>
<pre>&lt;%@ taglib uri="/WEB-INF/struts-tiles.tld" prefix="tiles" %&gt;</pre>
<strong>Servlet 2.3</strong>: You can omit the declaration in <code>WEB-INF/web.xml</code> and replace above line with the full URI:
<pre>&lt;%@ taglib uri="http://struts.apache.org/tags-tiles" prefix="tiles" %&gt;</pre>
<ul>
<li>
If you plan to use Tiles definitions defined in a centralized file, you need to create this file and instruct Struts to load the Tiles plugin which will create the factory corresponding to the file. You can have more than one definitions file.
<ul>
<li>
Create a file containing your definitions (e.g. <code>WEB-INF/tiles-defs.xml</code>). You can use the <code>tiles-defs.xml</code> file from the Tiles application for a detailed example of the required syntax.</li>
<li>
Setup the Tiles plugin in each <code>struts-config.xml</code> file corresponding to a module:
</li>
</ul>
<pre>
&lt;plug-in className="org.apache.struts.tiles.TilesPlugin" &gt;
&lt;set-property property="definitions-config" value="/WEB-INF/tiles-defs.xml,
/WEB-INF/tiles-tests-defs.xml" /&gt;
&lt;set-property property="definitions-parser-validate" value="true" /&gt;
&lt;set-property property="moduleAware" value="true" /&gt;
&lt;/plug-in&gt;</pre>
<ul>
<li>
<strong>Note:</strong> This plugin creates one factory for each Struts modules. The plugin first reads the factory parameters from <code>web.xml</code> and then overloads them with the ones defined in the first <code>struts-config.xml</code> file.
</li>
</ul>
</li>
</ul>
<ul>
<li>
<strong>Note:</strong> The Tiles framework now uses the commons-logging package to output different information or debug statements. Please refer to this package documentation to enable it. The simplest way to enable logging is to create two files in <code>WEB-INF/classes</code>:
<pre><strong>commons-logging.properties</strong>
org.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
<strong>simplelog.properties</strong>
# Logging detail level,
# Must be one of ("trace", "debug", "info", "warn", "error", or "fatal").
org.apache.commons.logging.simplelog.defaultlog=trace</pre>
</li>
</ul>
</section>
<section href="tiles" name="Tiles API Guide">
<ul>
<li>
A concise <a href="../api/org/apache/struts/tiles/package-summary.html#package_description">Tiles API Guide</a> is available to help you get started with the Tiles framework.
</li>
<li><a href="struts-tiles.html">Tiles Taglib Syntax Reference</a></li>
</ul>
</section>
<section href="resources" name="Tiles Resources">
<p>
<a href="http://www.oracle.com/technology/oramag/oracle/04-may/o34dev_struts.html">
<strong>Reuse Tiles and Simplify UI</strong></a> by James Holmes. Howto article in Oracle Magazine.
</p>
<p>
<a href="http://www.manning.com/getpage.html?project=husted&amp;filename=chapters.html">
<strong>Developing applications with Tiles</strong></a> by Cedric Dumoulin and Ted Husted.
Sample chapter from
<a href="http://www.amazon.com/exec/obidos/ISBN=1930110502/hitchhikeguidetoA/">Struts in Action</a>; available as a free download (PDF).
</p>
<p>
<a href="http://www.oreilly.com/catalog/jakarta/chapter/">
<strong>Using Tiles</strong></a> Sample beta chapter from
<a href="http://www.amazon.com/exec/obidos/ISBN=0596003285/hitchhikeguidetoA/">Programming Jakarta Struts</a>; available as a free download (PDF).
</p>
<p>
<a href="http://www-106.ibm.com/developerworks/java/library/j-strutstiles.html?loc=j">
<strong>Struts and Tiles aid component-based development</strong></a> by Wellie Chao.
</p>
<p>
<a href="http://www.javaworld.com/javaworld/jw-01-2002/jw-0104-tilestrut.html">
<strong>UI design with Tiles and Struts</strong></a> by Prakash Malani.
</p>
<p>
<a href="http://www.theserverside.com/resources/article.jsp?l=Tiles101">
<strong>Tiles 101/201</strong></a> by Patrick Peak.
</p>
<p>
<a href="http://www.lifl.fr/~dumoulin/tiles/tilesAdvancedFeatures.pdf">
<strong>Tiles Advanced Features</strong></a> by Cedric Dumoulin.
</p>
</section>
</chapter></body></document>