Author: apetrelli
Date: Thu May 17 05:53:47 2007
New Revision: 538897
URL: http://svn.apache.org/viewvc?view=rev&rev=538897
Log:
TILESSHARED-10
Completed "advanced topics".
Modified:
tiles/site/src/site/apt/tutorial/advanced/beans.apt
tiles/site/src/site/apt/tutorial/advanced/l10n.apt
tiles/site/src/site/apt/tutorial/advanced/menu.apt
tiles/site/src/site/apt/tutorial/index.apt
Modified: tiles/site/src/site/apt/tutorial/advanced/beans.apt
URL:
http://svn.apache.org/viewvc/tiles/site/src/site/apt/tutorial/advanced/beans.apt?view=diff&rev=538897&r1=538896&r2=538897
==============================================================================
--- tiles/site/src/site/apt/tutorial/advanced/beans.apt (original)
+++ tiles/site/src/site/apt/tutorial/advanced/beans.apt Thu May 17 05:53:47 2007
@@ -21,6 +21,103 @@
Attribute as Beans
-----------
-Introduction
+Beans as attributes
- This is the introduction
+ You can put objects (usually beans) as attribute values. This feature is
+ useful if you want to use Tiles-scoped objects (for example menus,
+ layout-related objects, etc.), instead of relying on servlet scopes (request,
+ session, application).
+
+* Declaring beans in definitions file
+
+ You can declare a bean by using the
+
{{{../../framework/tiles-core/dtddoc/tiles-config_2_0.dtd.html#bean}<<<\<bean\>>>>}}
+ element in Tiles definition files. It can be used only in
+ {{{list-attributes.html}list attributes}}.
+
+---------------------------------------
+<definition name="myapp.homepage.objects"
template="/layouts/variable_objects.jsp">
+ <put-list-attribute name="items">
+ <bean classtype="my.package.MyClassName">
+ <set-property name="propertyName1" value="value1" />
+ <set-property name="propertyName2" value="value2" />
+ </bean>
+ <add-attribute value="/tiles/common_menu.jsp" />
+ <add-attribute value="/tiles/credits.jsp" />
+ </put-list-attribute>
+</definition>
+---------------------------------------
+
+ This feature is not very powerful, and it has been maintained for backward
+ compatibility.
+
+* Bean injection
+
+ Attribute values can be "injected" when needed, getting them from an external
+ area, such as servlet scopes (request, session, application). It can be done
+ by using the APIs or JSP tags.
+
+** Bean injection using APIs
+
+ Beans can be injected by using the APIs, before rendering a definition, by
+ filling <<<AttributeContext>>> attributes with the desired values.
+
+-----------------------------------
+TilesContainer container = TilesAccess.getContainer(
+ request.getSession().getServletContext());
+AttributeContext attributeContext = container.startContext(request, response);
+attributeContext.putAttribute("attributeName", new MyClass());
+container.render("myapp.homepage", request, response);
+container.endContext(request, response);
+-----------------------------------
+
+ The <<<attributeName>>> attribute will be filled with an instance of
+ <<<MyClass>>>.
+
+ The best way to inject beans in definitions is by using
+ {{{preparer.html}preparers}}. The <<<AttributeContext>>> in the <<<execute>>>
+ method of a view preparer is exactly the attribute context of the definition
+ that is going to be rendered.
+
+** Bean injection using JSP tags
+
+ You can inject beans as attributes by using <<<\<tiles:putAttribute\>>>> JSP
+ tag: its <<<value>>> attribute can accept EL expressions, so, if you have a
+ bean stored in some accessible scope (such as request, session and
+ application) you can inject it as an attribute value.
+
+--------------------------------------
+<tiles:insertDefinition name="my.definition">
+ <tiles:putAttribute name="myAttribute" value="${requestScope.myBean}" />
+</tiles:insertDefinition>
+--------------------------------------
+
+ In this case, the <<<my.definition>>> definition is rendered using as
+ "myAttribute" value the bean resolved by the EL expression.
+
+* Using attribute beans
+
+ To use an attribute value that is a bean, you must <<import>> it or <<use>>
+ it.
+
+ To import an attribute you have to use the
+
{{{../../framework/tiles-jsp/tlddoc/tiles/importAttribute.html}<<<\<tiles:importAttribute\>>>>}}
+ tag:
+
+--------------------------------------
+<tiles:importAttribute name="myAttribute" />
+--------------------------------------
+
+ In this case, the "myAttribute" value is imported as a bean in page scope,
+ named "myAttribute" too.
+
+ To use an attribute, you have to use the
+
{{{../../framework/tiles-jsp/tlddoc/tiles/useAttribute.html}<<<\<tiles:useAttribute\>>>>}}
+ tag:
+
+--------------------------------------
+<tiles:useAttribute name="myAttribute" />
+--------------------------------------
+
+ A scripting variable, called "myAttribute" will be created, together with a
+ paged scoped bean as in <<<\<tiles:importAttribute\>>>>.
Modified: tiles/site/src/site/apt/tutorial/advanced/l10n.apt
URL:
http://svn.apache.org/viewvc/tiles/site/src/site/apt/tutorial/advanced/l10n.apt?view=diff&rev=538897&r1=538896&r2=538897
==============================================================================
--- tiles/site/src/site/apt/tutorial/advanced/l10n.apt (original)
+++ tiles/site/src/site/apt/tutorial/advanced/l10n.apt Thu May 17 05:53:47 2007
@@ -21,6 +21,115 @@
Tiles Localization
-----------
-Introduction
+Localization support
- This is the introduction
+ Customizing pages for different locales in a common practice: in real-world
+ websites you can see different sites for different languages and countries.
+
+ It can be a matter of changing the layout (for example, in Arab countries the
+ menu should stay on the right, instead of the left), or providing alternate
+ content.
+
+* Creating localized definitions
+
+ Localization is immediately available. To use the benefits of localization
you
+ have to create different Tiles definition files for each locale you want to
+ support: it's simply a matter of appending the locale code at the end of the
+ file name (just like <<<.properties>>> files in resource bundles).
+
+ For example, if you have the <<<tiles-defs.xml>>> file and you want to
support
+ French and Italian locale, you have to create at least three files:
+
+--------------------------------
+tiles-defs.xml
+tiles-defs_fr.xml
+tiles-defs_it.xml
+--------------------------------
+
+ You can also distinguish between different languages in different country. So
+ if you want to distinguish between British English and American English, you
+ can create these files:
+
+--------------------------------
+tiles-defs_en_GB.xml
+tiles-defs_en_US.xml
+--------------------------------
+
+ and so on.
+
+* Inheritance between localizations
+
+ If you want to support different locales, you don't have to rewrite all the
+ definitions, but only those that differ from the main definitions file. In
+ other words, locale-specific definition files contains the "overrides" to the
+ default definitions.
+
+ For example, suppose that the following definition is declared in
+ <<<tiles-defs.xml>>>:
+
+------------------------------------
+<definition name="myapp.homepage" template="/layouts/classic.jsp">
+ <put-attribute name="title" value="Tiles tutorial homepage" />
+ <put-attribute name="header" value="/tiles/banner.jsp" />
+ <put-attribute name="menu" value="/tiles/common_menu.jsp" />
+ <put-attribute name="body" value="myapp.homepage.body" />
+ <put-attribute name="footer" value="/tiles/credits.jsp" />
+</definition>
+
+<definition name="myapp.homepage.body" template="/layouts/three_rows.jsp">
+ <put-attribute name="one" value="/tiles/headlines.jsp" />
+ <put-attribute name="two" value="/tiles/topics.jsp" />
+ <put-attribute name="one" value="/tiles/comments.jsp" />
+</definition>
+------------------------------------
+
+ In <<<tiles-defs_it.xml>>> there is a new declaration of <<<myapp.homepage>>>
+ definition:
+
+------------------------------------
+<definition name="myapp.homepage" template="/layouts/classic.jsp">
+ <put-attribute name="title" value="Pagina iniziale del tutorial di Tiles" />
+ <put-attribute name="header" value="/tiles/banner.jsp" />
+ <put-attribute name="menu" value="/tiles/common_menu.jsp" />
+ <put-attribute name="body" value="myapp.homepage.body" />
+ <put-attribute name="footer" value="/tiles/credits.jsp" />
+</definition>
+------------------------------------
+
+ Using "it" locale, the title will be different from the default, while the
+ rest remains the same.
+
+ Notice that the <<<myapp.homepage.body>>> definition is the one defined in
+ the default definitions file: you still can reference to the default
+ definitions, both when composing and when extending.
+
+ You can also override a <<definition that is extended>>. In this case, when
+ resolving inheritance, the overridden definition will be taken as a basis.
+ For example, if in <<<tiles-defs.xml>>> there are the following definitions:
+
+------------------------------------
+<definition name="myapp.page.common" template="/layouts/classic.jsp">
+ <put-attribute name="header" value="/tiles/banner.jsp" />
+ <put-attribute name="menu" value="/tiles/common_menu.jsp" />
+ <put-attribute name="footer" value="/tiles/credits.jsp" />
+</definition>
+
+<definition name="myapp.bugs" extends="myapp.page.common">
+ <put-attribute name="title" value="Bugs" />
+ <put-attribute name="body" value="myapp.homepage.body" />
+</definition>
+------------------------------------
+
+ If in <<<tiles-defs_it.xml>>> you define the following definition:
+
+------------------------------------
+<definition name="myapp.page.common" template="/layouts/classic.jsp">
+ <put-attribute name="header" value="/tiles/banner_it.jsp" />
+ <put-attribute name="menu" value="/tiles/common_menu_it.jsp" />
+ <put-attribute name="footer" value="/tiles/credits_it.jsp" />
+</definition>
+------------------------------------
+
+ The <<<myapp.bugs>>> will extend the latter definition, and not the default!
+ This is useful if you want to change an abstract definition for a locale,
+ without redefining all the definitions.
Modified: tiles/site/src/site/apt/tutorial/advanced/menu.apt
URL:
http://svn.apache.org/viewvc/tiles/site/src/site/apt/tutorial/advanced/menu.apt?view=diff&rev=538897&r1=538896&r2=538897
==============================================================================
--- tiles/site/src/site/apt/tutorial/advanced/menu.apt (original)
+++ tiles/site/src/site/apt/tutorial/advanced/menu.apt Thu May 17 05:53:47 2007
@@ -21,6 +21,30 @@
Tiles Menu-ing support
-----------
-Introduction
+Menu-ing support
- This is the introduction
+ Tiles offers a (pretty small) support to create menus. It consists in
allowing
+ creation of menu-like beans, to be defined in Tiles definition files, using
+ the
{{{../../framework/tiles-core/dtddoc/tiles-config_2_0.dtd.html#item}<<<\<item\>>>>}}
+ element:
+
+-------------------------------------------
+<definition name="my.definition" layout="/layout/my-template.jsp">
+ <put-list-attribute name="myListAttribute">
+ <item value="Home page" link="menu.do" />
+ <item value="News" link="news.do" />
+ </put-list-attribute>
+</definition>
+-------------------------------------------
+
+ To use it, in your JSP pages include:
+
+-------------------------------------------
+<tiles:importAttribute name="myListAttribute />
+<c:forEach var="item" items="${myListAttribute}">
+ <a href="${item.link">${item.value}</a>
+ <br/>
+</c:forEach>
+-------------------------------------------
+
+ That's it!
Modified: tiles/site/src/site/apt/tutorial/index.apt
URL:
http://svn.apache.org/viewvc/tiles/site/src/site/apt/tutorial/index.apt?view=diff&rev=538897&r1=538896&r2=538897
==============================================================================
--- tiles/site/src/site/apt/tutorial/index.apt (original)
+++ tiles/site/src/site/apt/tutorial/index.apt Thu May 17 05:53:47 2007
@@ -49,7 +49,7 @@
[[4]] {{{advanced/preparer.html}View Preparers}}
- [[5]] {{{utils.html}Rendering Utilities}}
+ [[5]] {{{utils.html}Rendering Utilities}}
[[6]] {{{advanced/l10n.html}Tiles Localization}}
