| <!-- |
| /* |
| * $Id$ |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| --> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> |
| <html lang="en"> |
| <head> |
| <title>Tiles Package</title> |
| </head> |
| <body> |
| <div class="mainContent"> |
| The Tiles taglib and framework allows building web pages by assembling reusable |
| pieces of pages, called Tiles. A Tiles is usually a simple JSP page. |
| |
| <div class="section"> |
| <h2>Introduction</h2> |
| |
| <p>The Tiles framework allows building pages by assembling reusable Tiles. |
| As an example, the page in the next figure can be build by assembling a |
| header, a footer, a menu and a body.</p> |
| |
| <p><img src="doc-files/image001.gif" height="169" width="145" alt="doc-files/image001"></p> |
| |
| <p>Each Tiles (header, menu, body, ...) is a JSP page and can itself be build |
| by assembling other Tiles.</p> |
| |
| <p>Using Tiles can be compared as using Java methods: You need to define the Tiles (the method body), and then you |
| can "call" this body anywhere you want, passing it some parameters. In Tiles, parameters are called |
| "attributes" in order to avoid confusion with the request parameters.</p> |
| |
| <p>The Tiles body can be a simple JSP page, a Struts action or any URI pointing |
| to a resource inside the current web site.</p> |
| |
| <p>Inserting the body, or calling it, is done with the tag <tiles:insert |
| ...> anywhere in a JSP page. Insertion can also be done by specifying |
| a <em>definition name </em>as the path of a Struts forward or as input, |
| forward or include attributes of a Struts action.</p> |
| |
| <p>Tiles bodies are used to create layouts, reusable parts, ... Tiles insertions |
| are used to insert Tiles. The same Tiles can be reused several times in |
| the same site, or even in the same page.</p> |
| |
| <p>Insertion of a Tiles body can be associated to a logical name in what Tiles calls a "definition". A |
| definition contains a logical name, a page used as body and some attribute values. The definition declaration |
| doesn't insert the associated Tiles body. It just associates it with the name. A definition name can be used |
| anywhere insertion of a Tiles body can occur. The associated Tiles body is then inserted with associated |
| attributes.</p> |
| |
| <p>The definition declarations can be done in JSP pages or in one or more |
| centralized files. A definition can extend another one, overload some attributes, |
| add new attributes ... This allows the declaration of a "master" definition |
| declaring the common layout, header, menu and footer. All other definitions |
| extend this master layout thereby making it possible to change the entire |
| site look & feel simply by changing the master definition. </p> |
| </div> |
| <div class="section"> |
| <h2>Simple Examples</h2> |
| |
| <div class="subsection1"> |
| <h3>Insert a JSP page</h3> |
| <pre><tiles:insert <strong>page</strong>="/layouts/commonLayout.jsp" flush="true" /> |
| </pre> |
| <p>This example inserts the specified page in place of the tag. The page attribute is any valid URL pointing to |
| a resource inside the current site.</p> |
| </div> |
| <div class="subsection1"> |
| <a name="doc.InsertPageWithAttributes"></a> |
| |
| <h3>Insert a Tiles passing some attributes</h3> |
| <pre> |
| <tiles:insert page="/layouts/classicLayout.jsp" flush=&quot;true"> |
| <tiles:put name="title" value="Page Title" /> |
| <tiles:put name="header" value="/common/header.jsp" /> |
| <tiles:put name="footer" value="/common/footer.jsp" /> |
| <tiles:put name="menu" value="/common/menu.jsp" /> |
| <tiles:put name="body" value="/tiles/mainBody.jsp" /> |
| </tiles:insert> |
| </pre> |
| <p>This example inserts the specified page, passing it the attributes. Attributes |
| are stored in a Tiles context which is passed to the inserted pag and |
| can then be accesssed by their names.</p> |
| </div> |
| <div class="subsection1"> |
| <h3>Retrieve an attribute value as String</h3> |
| <pre> |
| <tiles:getAsString name="title" /> |
| </pre> |
| <p>This example retrieves the value of the attribute "title" and prints it as a String in the current |
| output stream. The method toString() is applied on the attribute value, allowing to pass any kind of object |
| as value.</p> |
| </div> |
| <div class="subsection1"> |
| <h3>Insert Tiles referenced by an attribute</h3> |
| <pre> |
| <tiles:insert attribute='menu' /> |
| </pre> |
| <p>This inserts the Tiles referenced by the attribute "menu" value. The |
| specified attribute value is first retrieved from current Tiles's context, |
| and then the value is used as a page target to insert.</p> |
| </div> |
| <div class="subsection1"> |
| <h3>Classic Layout </h3> |
| |
| <p>This example is a layout assembling a page in the classic header-footer-menu-body |
| fashion.</p> |
| <pre> |
| <%@ taglib uri="http://tiles.apache.org/tags-tiles" prefix="tiles" %> |
| <HTML> |
| <HEAD> |
| <link rel="stylesheet" href="<%=request.getContextPath()%>/layouts/stylesheet.css" |
| type="text/css"/> |
| <title><tiles:getAsString name="title"/></title> |
| </HEAD> |
| <body> |
| <table border="0" width="100%" cellspacing="5"> |
| <tr> |
| <td colspan="2"><tiles:insert attribute="header" /></td> |
| </tr> |
| <tr> |
| <td width="140" valign="top"> |
| <tiles:insert attribute='menu' /> |
| </td> |
| <td valign="top" align="left"> |
| <tiles:insert attribute='body' /> |
| </td> |
| </tr> |
| <tr> |
| <td colspan="2"> |
| <tiles:insert attribute="footer" /> |
| </td> |
| </tr> |
| </table> |
| </body> |
| </html> |
| </pre> |
| <p>The layout is declared in a JSP page (ex: /layouts/classicLayout.jsp). |
| It can be used in conjunction with the tag described in "<a href="#doc.InsertPageWithAttributes">Insert |
| a page passing some attributes</a>". </p> |
| </div> |
| </div> |
| <div class="section"> |
| <h2>Definitions</h2> |
| |
| <p>A definition associates a logical name with the URL of a Tiles to be inserted |
| and some attribute values. A definition doesn't insert the Tiles. This is |
| done later using the definition name. A definition name can be inserted |
| as often as you want in your site, making it easy to reuse a Tiles. </p> |
| |
| <p>A definition can extend another definition and overload some attributes |
| or add new ones. This makes easy factorization of definitions differing |
| by some attributes. For example, you can define a master definition declaring |
| the main header, menu, footer, and a default title. Then let each of your |
| page definitions extend this master definition and overload the title and |
| the body.</p> |
| |
| <p>Definitions can be declared in a JSP page, or in one or more centralized |
| files. To enable the definitions from centralized files, you need to initialize |
| the "definitions factory&&quot; which will parse the definitions from the files |
| and provide them to the Tiles framework.</p> |
| |
| <div class="subsection1"> |
| <h3>Enabling Definition Factory</h3> |
| |
| <p>To enable Tiles definitions described in one or more files, you need to write these files and to initialize the |
| definition factory. </p> |
| |
| <p>Initialization is different depending on the Struts version you use, |
| or if you do not use Struts at all.</p> |
| |
| <div class="subsection2"> |
| <h4>Struts1.1</h4> |
| |
| <p>Use the Tiles plug-in to enable Tiles definitions. This plug-in creates |
| the definition factory and passese it a configuration object populated |
| with parameters. Parameters can be specified in the web.xml file or |
| as plug-in parameters. The plug-in first reads parameters from web.xml, |
| and then overloads them with the ones found in the plug-in. All parameters |
| are optional and can be omitted. The plug-in should be declared in each |
| struts-config file:</p> |
| <pre> |
| <plug-in className=&&quot;org.apache.struts.tiles.TilesPlugin&&quot; > |
| <set-property property=&&quot;definitions-config&&quot; |
| value=&&quot;/WEB-INF/tiles-defs.xml, |
| /WEB-INF/tiles-tests-defs.xml,/WEB-INF/tiles-tutorial-defs.xml, |
| /WEB-INF/tiles-examples-defs.xml&&quot; /> |
| <set-property property=&&quot;moduleAware&&quot; value=&&quot;true&&quot; /> |
| <set-property property=&&quot;org.apache.tiles.definition.digester.DigesterDefinitionsReader.PARSER_VALIDATE&&quot; value=&&quot;true&&quot; /> |
| </plug-in> |
| </pre> |
| <ul> |
| <li>definitions-config: (optional) |
| <ul> |
| <li>Specify configuration file names. There can be several comma separated file names (default: ?? ) |
| </li> |
| </ul> |
| </li> |
| <li>org.apache.tiles.definition.digester.DigesterDefinitionsReader.PARSER_VALIDATE: (optional) |
| <ul> |
| <li>Specify if XML parser should validate the Tiles configuration |
| file |
| <ul> |
| <li>true : validate. DTD should be specified in file header (default)</li> |
| <li>false : no validation</li> |
| |
| </ul> |
| </li> |
| </ul> |
| </li> |
| |
| <li>moduleAware: (optional) |
| <ul> |
| <li>Specify if the Tiles definition factory is module aware. If true (default), |
| there will be one factory for each Struts module. |
| If false, there will be one common factory for all module. In this later case, |
| it is still needed to declare one plugin per module. The factory will be |
| initialized with parameters found in the first initialized plugin (generally the |
| one associated with the default module). |
| <ul> |
| <li>true : Tiles framework is module aware</li> |
| <li>false :Tiles framework has one single factoy shared among modules (default)</li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| |
| <li>tilesUtilImplClassname: (optional - for advanced user) |
| <ul> |
| <li>Specify The classname of the TilesUtil implementation to use. The specified class should |
| be a subclass of TilesUtilStrutsImpl. This option disable the moduleAware option. |
| <br>Specifying &&"TilesUtilStrutsImpl&&" is equivalent to moduleAware = |
| false. |
| <br>Specifying &&"TilesUtilStrutsModuleImpl&&" is equivalent to moduleAware |
| = true. |
| This option is taken into account only once, when it is first encountered. To avoid problems, |
| it is advice to specify the same values in all TilesPlugin declaration. |
| </li> |
| </ul> |
| </li> |
| |
| </ul> |
| <p>The TilesPlugin class creates one definition factory for each struts module. |
| </p> |
| |
| <p> |
| If the flag moduleAware is false, only one shared factory is created for all modules. |
| In this later case, the factory is initialized with parameters found in the first plugin. |
| The plugins should be declared in all modules, and the moduleAware flag should be |
| the same for the entire application.</p> |
| |
| <p> |
| Paths found in Tiles definitions are relative to the main context.</p> |
| |
| <p>You don't need to specify a TilesRequestProcessor, this is automatically |
| done by the plug-in. If, however, you want to specify your own RequestProcessor, |
| it should extend the TilesRequestProcessor. The plug-in checks this |
| constraint.</p> |
| </div> |
| <div class="subsection2"> |
| <h4>Struts1.0.x</h4> |
| |
| <p>You need to use a special servlet extending the Struts servlet. This is specified in the web.xml file of your |
| application:</p> |
| <pre> |
| <servlet> |
| <servlet-name>action</servlet-name> |
| <servlet-class>org.apache.tiles.web.startup.TilesServlet</servlet-class> |
| <!-- Tiles Servlet parameter |
| Specify configuration file names. There can be several comma |
| separated file names |
| --> |
| <init-param> |
| <param-name>definitions-config</param-name> |
| <param-value>/WEB-INF/tiles-defs.xml</param-value> |
| </init-param> |
| <!-- Tiles Servlet parameter |
| Specify if XML parser should validate the Tiles configuration file(s). |
| true : validate. DTD should be specified in file header. |
| false : no validation |
| --> |
| <init-param> |
| <param-name>org.apache.tiles.definition.digester.DigesterDefinitionsReader.PARSER_VALIDATE</param-name> |
| <param-value>true</param-value> |
| </init-param> |
| ... |
| </servlet> |
| </pre> |
| </div> |
| <div class="subsection2"> |
| <h4>Without Struts</h4> |
| |
| <p>Tiles can be used without Struts. To initialize the definition factory, you can use the provided servlet. Declare |
| it in the web.xml file of your application:</p> |
| <pre> |
| <servlet> |
| <servlet-name>action</servlet-name> |
| <servlet-class>org.apache.struts.tiles.TilesServlet</servlet-class> |
| |
| |
| <init-param> |
| <param-name>definitions-config</param-name> |
| <param-value>/WEB-INF/tiles-defs.xml</param-value> |
| </init-param> |
| <init-param> |
| <param-name>org.apache.tiles.definition.digester.DigesterDefinitionsReader.PARSER_VALIDATE</param-name> |
| <param-value>true</param-value> |
| </init-param> |
| ... |
| </pre> |
| <p>The parameters are the same as for Struts1.1 or 1.0.</p> |
| </div> |
| </div> |
| <div class="subsection1"> |
| <h3>Definition File Syntax</h3> |
| |
| <p>The definition file syntax can be found in the |
| <a href="http://tiles.apache.org/dtds/tiles-config_2_0.dtd">tiles-config_2_0.dtd file</a>. |
| </p> |
| |
| <p>Following is a simple example:</p> |
| <pre> |
| <!DOCTYPE tiles-definitions PUBLIC |
| &&quot;-//Apache Software Foundation//DTD Tiles Configuration//EN&&quot; |
| &&quot;http://tiles.apache.org/dtds/tiles-config_2_0.dtd&&quot;> |
| |
| <!-- Definitions for Tiles documentation --> |
| <tiles-definitions> |
| |
| <!-- ========================================================== --> |
| <!-- Master definition --> |
| <!-- ========================================================== --> |
| <!-- Main page layout used as a root for other page definitions --> |
| |
| <definition name=&&quot;site.mainLayout&&quot; template=&&quot;/layouts/classicLayout.jsp&&quot;> |
| <put name=&&quot;title&&quot; value=&&quot;Tiles Blank Site&&quot; /> |
| <put name=&&quot;header&&quot; value=&&quot;/tiles/common/header.jsp&&quot; /> |
| <put name=&&quot;menu&&quot; value=&&quot;site.menu.bar&&quot; /> |
| <put name=&&quot;footer&&quot; value=&&quot;/tiles/common/footer.jsp&&quot; /> |
| <put name=&&quot;body&&quot; value=&&quot;/tiles/body.jsp&&quot; /> |
| </definition> |
| |
| <!-- ========================================================== --> |
| <!-- Index page definition --> |
| <!-- ========================================================== --> |
| <!-- This definition inherits from the main definition. |
| It overloads the page title and the body used. |
| Use the same mechanism to define new pages sharing common |
| properties (here header, menu, footer, layout) |
| --> |
| |
| <definition name=&&quot;site.index.page&&quot; extends=&&quot;site.mainLayout&&quot; > |
| <put name=&&quot;title&&quot; value=&&quot;Tiles Blank Site Index&&quot; /> |
| <put name=&&quot;body&&quot; value=&&quot;/tiles/body.jsp&&quot; /> |
| </definition> |
| |
| </tiles-definition> |
| </pre> |
| </div> |
| <div class="subsection1"> |
| <h3>Debugging</h3> |
| |
| <p>To debug a page made of Tiles, you can use following advices:</p> |
| <ul> |
| <li>Check each Tiles separatly. Try to access nested Tiles directly to test |
| if thes work properly. |
| </li> |
| <li>Enable Tiles logging. See the commons-logging package help.</li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
