You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tiles.apache.org by ap...@apache.org on 2007/04/12 12:19:58 UTC
svn commit: r527870 [2/2] - in /tiles/framework/trunk:
tiles-api/src/main/java/org/apache/tiles/
tiles-api/src/main/java/org/apache/tiles/access/
tiles-api/src/main/java/org/apache/tiles/mgmt/
tiles-api/src/main/java/org/apache/tiles/web/ tiles-core/sr...
Added: tiles/framework/trunk/tiles-jsp/src/main/java/org/apache/tiles/package.html
URL: http://svn.apache.org/viewvc/tiles/framework/trunk/tiles-jsp/src/main/java/org/apache/tiles/package.html?view=auto&rev=527870
==============================================================================
--- tiles/framework/trunk/tiles-jsp/src/main/java/org/apache/tiles/package.html (added)
+++ tiles/framework/trunk/tiles-jsp/src/main/java/org/apache/tiles/package.html Thu Apr 12 03:19:41 2007
@@ -0,0 +1,390 @@
+<!--
+/*
+ * $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;definitions-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>definitions-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 &&quot;TilesUtilStrutsImpl&&quot; is equivalent to moduleAware =
+ false.</br>
+ <br>Specifying &&quot;TilesUtilStrutsModuleImpl&&quot; is equivalent to moduleAware
+ = true.</br>
+ 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.servlet.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>definitions-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>definitions-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>
Propchange: tiles/framework/trunk/tiles-jsp/src/main/java/org/apache/tiles/package.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: tiles/framework/trunk/tiles-jsp/src/main/java/org/apache/tiles/package.html
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Added: tiles/framework/trunk/tiles-test/src/main/java/org/apache/tiles/test/preparer/package.html
URL: http://svn.apache.org/viewvc/tiles/framework/trunk/tiles-test/src/main/java/org/apache/tiles/test/preparer/package.html?view=auto&rev=527870
==============================================================================
--- tiles/framework/trunk/tiles-test/src/main/java/org/apache/tiles/test/preparer/package.html (added)
+++ tiles/framework/trunk/tiles-test/src/main/java/org/apache/tiles/test/preparer/package.html Thu Apr 12 03:19:41 2007
@@ -0,0 +1,30 @@
+<!--
+/*
+ * $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.
+ */
+-->
+<html>
+<head>
+ <title>Tiles preparer test package</title>
+</head>
+<body>
+Test classes to check preparer functionality.
+</body>
+</html>
\ No newline at end of file
Propchange: tiles/framework/trunk/tiles-test/src/main/java/org/apache/tiles/test/preparer/package.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: tiles/framework/trunk/tiles-test/src/main/java/org/apache/tiles/test/preparer/package.html
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Added: tiles/framework/trunk/tiles-test/src/main/java/org/apache/tiles/test/servlet/package.html
URL: http://svn.apache.org/viewvc/tiles/framework/trunk/tiles-test/src/main/java/org/apache/tiles/test/servlet/package.html?view=auto&rev=527870
==============================================================================
--- tiles/framework/trunk/tiles-test/src/main/java/org/apache/tiles/test/servlet/package.html (added)
+++ tiles/framework/trunk/tiles-test/src/main/java/org/apache/tiles/test/servlet/package.html Thu Apr 12 03:19:41 2007
@@ -0,0 +1,30 @@
+<!--
+/*
+ * $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.
+ */
+-->
+<html>
+<head>
+ <title>Tiles servlet test package</title>
+</head>
+<body>
+Test servlet classes.
+</body>
+</html>
\ No newline at end of file
Propchange: tiles/framework/trunk/tiles-test/src/main/java/org/apache/tiles/test/servlet/package.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: tiles/framework/trunk/tiles-test/src/main/java/org/apache/tiles/test/servlet/package.html
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL