cedric 2002/09/12 01:38:26
Modified: src/share/org/apache/struts/tiles package.html
Log:
Documentation update.
Proposed by Yann Cébron [EMAIL PROTECTED]
Revision Changes Path
1.2 +98 -44 jakarta-struts/src/share/org/apache/struts/tiles/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/jakarta-struts/src/share/org/apache/struts/tiles/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 26 Jul 2002 13:17:30 -0000 1.1
+++ package.html 12 Sep 2002 08:38:26 -0000 1.2
@@ -4,25 +4,39 @@
</head>
<body>
<div class="mainContent">
-<p>The Tiles taglib and framework allows building web pages by assembling reusable
piece of pages, called Tiles. A Tiles is usually a simple jsp page.</p>
+ <p>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.</p>
<div class="section">
<h2>Introduction</h2>
-<p>The Tiles framework allows building pages by assembling reusable Tiles. As
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="130,8" width="112,8"
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>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 insertion are
used to insert a Tiles. A same Tiles can be reused several times in the same site, or
even in the same page.</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 extends 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 others definitions extend this master
layout. Then, it is possible to change the entire site look & feel simply by
changing the master definition. </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>
-<p class="CodewithBorder"><tiles:insert
<strong>page</strong>="/layouts/commonLayout.jsp" flush="true"/></p>
+ <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>
@@ -37,32 +51,37 @@
<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 page. This later can
then access the attribute values by their names.</p>
+ <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>
-<p class="CodewithBorder"><tiles:getAsString name="title"/></p>
+<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>
-<p class="CodewithBorder"><tiles:insert attribute='menu'/></p>
+<tiles:insert attribute='menu' />
</pre>
-<p>This inserts the tiles referenced by the attribute "menu" value. The specified
attribute value is first retrieve from current Tiles context, and then the value is
used as a page target to insert.</p>
+ <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>
+ <p>This example is a layout assembling a page in the classic
header-footer-menu-body
+ fashion.</p>
+ <pre>
<%@ taglib uri="/WEB-INF/struts-tiles.tld" prefix="tiles" %>
<HTML>
<HEAD>
<link rel=stylesheet
href="<%=request.getContextPath()%>/layouts/stylesheet.css"
type="text/css">
- <title><tiles:getAsString name="title"/></title>
+ <title><tiles:getAsString name="title"/ ></title>
</HEAD>
<body>
<table border="0" width="100%" cellspacing="5">
@@ -71,7 +90,7 @@
</tr>
<tr>
<td width="140" valign="top">
- <tiles:insert attribute='menu'/>
+ <tiles:insert attribute='menu' />
</td>
<td valign="top" align="left">
<tiles:insert attribute='body' />
@@ -86,21 +105,41 @@
</body>
</html>
</pre>
-<p>Such layout is declared in a jsp page (ex: /layouts/classicLayout.jsp). It can
be used in conjunction with the tag described in "<a href="#_Insert_a_page_passing
some attribut">Insert a page passing some attributes</a>". </p>
+ <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="#_Insert_a_page_passing some attribut">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 easy to reuse a Tiles. </p>
-<p>A definition can extend another definition and overload some attributes or
adding new ones. This make 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 definition extends this
master definition and overloads 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" which will parse the definitions from the files and serves them
to the tiles framework.</p>
+ <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" 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 regarding the Struts version you use, or if you do
not use Struts at all.</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 pass it a configuration object populated with parameters
explained here after. Parameters can be specified in the web.xml file or as the
plug-in parameters. The plug-in first read parameters from web.xml, and then overload
them with the one 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>
+ <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="org.apache.struts.tiles.TilesPlugin" >
<set-property property="definitions-config"
@@ -117,7 +156,8 @@
<li>Specify configuration file names. There can be several comma separated file
names (default: ?? )</li>
</ul>
</li>
-<li>definitions-debug: (optional<ul>
+ <li>definitions-debug: (optional)
+<ul>
<li>Specify Tiles debug level<ul>
<li>0 : no debug information</li>
<li>1 : debug information</li>
@@ -126,7 +166,8 @@
</li>
</ul>
</li>
-<li>definitions-parser-details: (optional<ul>
+ <li>definitions-parser-details: (optional)
+<ul>
<li>Specify Digester debug level. This value is passed to Digester<ul>
<li>0 : no debug information (default)</li>
<li>1 : debug information</li>
@@ -135,22 +176,30 @@
</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>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>
</ul>
-<p>The TilesPlugin class create one single definition factory shared by all struts
modules, even if the plugin is declared several times. 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, this later
should extends the TilesRequestProcessor. The plug-in checks check this constraint.</p>
+ <p>The TilesPlugin class creates one single definition factory shared
+ by all Struts modules, even if the plugin is declared several times.
+ 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>
+ <pre>
<servlet>
<servlet-name>action</servlet-name>
<servlet-class>org.apache.struts.tiles.ActionComponentServlet</servlet-class>
@@ -183,7 +232,7 @@
<param-value>0</param-value>
</init-param>
<!-- Tiles Servlet parameter
- Specify if xml parser should validate the Tiles configuration file.
+ Specify if XML parser should validate the Tiles configuration file(s).
true : validate. DTD should be specified in file header.
false : no validation
-->
@@ -229,17 +278,19 @@
<h3>Definition File Syntax</h3>
<p>The definition file syntax can be found in the struts-tiles.dtd file.</p>
<p>Following is a simple example:</p>
-<pre>
+ <pre>
<!DOCTYPE tiles-definitions PUBLIC
"-//Apache Software Foundation//DTD Tiles Configuration//EN"
"http://jakarta.apache.org/struts/dtds/tiles-config.dtd">
+
<!-- Definitions for Tiles documentation -->
<tiles-definitions>
- <!-- ======================================================= -->
- <!-- Master definition
-->
- <!-- ======================================================= -->
- <!-- Main page layout used as a root for other pages defintion.
- -->
+
+ <!-- ========================================================== -->
+ <!-- Master definition -->
+ <!-- ========================================================== -->
+ <!-- Main page layout used as a root for other page definitions -->
+
<definition name="site.mainLayout" path="/layouts/classicLayout.jsp">
<put name="title" value="Tiles Blank Site" />
<put name="header" value="/tiles/common/header.jsp" />
@@ -247,18 +298,21 @@
<put name="footer" value="/tiles/common/footer.jsp" />
<put name="body" value="/tiles/body.jsp" />
</definition>
- <!-- ======================================================= -->
- <!-- Index page definition
-->
- <!-- ======================================================= -->
+
+ <!-- ========================================================== -->
+ <!-- Index page definition -->
+ <!-- ========================================================== -->
<!-- This definition inherits from the main definition.
- It overload the page title, and the body used.
+ 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="site.index.page" extends="site.mainLayout" >
<put name="title" value="Tiles Blank Site Index" />
<put name="body" value="/tiles/body.jsp" />
</definition>
+
</tiles-definition>
</pre>
</div>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
