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 2009/05/12 23:41:29 UTC
svn commit: r774103 - in /tiles/framework/trunk/src/site:
apt/tutorial/extension/index.apt apt/tutorial/extension/template.apt
apt/tutorial/integration/freemarker.apt
apt/tutorial/integration/velocity.apt apt/tutorial/integration/view.apt
site.xml
Author: apetrelli
Date: Tue May 12 21:41:29 2009
New Revision: 774103
URL: http://svn.apache.org/viewvc?rev=774103&view=rev
Log:
TILES-407
Added documentation for FreeMarker and Velocity support and for supporting template languages.
Added:
tiles/framework/trunk/src/site/apt/tutorial/extension/template.apt
tiles/framework/trunk/src/site/apt/tutorial/integration/velocity.apt
Modified:
tiles/framework/trunk/src/site/apt/tutorial/extension/index.apt
tiles/framework/trunk/src/site/apt/tutorial/integration/freemarker.apt
tiles/framework/trunk/src/site/apt/tutorial/integration/view.apt
tiles/framework/trunk/src/site/site.xml
Modified: tiles/framework/trunk/src/site/apt/tutorial/extension/index.apt
URL: http://svn.apache.org/viewvc/tiles/framework/trunk/src/site/apt/tutorial/extension/index.apt?rev=774103&r1=774102&r2=774103&view=diff
==============================================================================
--- tiles/framework/trunk/src/site/apt/tutorial/extension/index.apt (original)
+++ tiles/framework/trunk/src/site/apt/tutorial/extension/index.apt Tue May 12 21:41:29 2009
@@ -25,8 +25,9 @@
Tiles is not a static framework: it can be customized and extended for your
needs, to provide custom behaviour to different aspects of the application.
-
+
[[1]] {{{points.html}Extension Points}}.
- [[2]] {{{url_definitions_factory.html}Customizing <<<UrlDefinitionsFactory>>>}}.
-
\ No newline at end of file
+ [[2]] {{{template.html}Adding support to a template language}}.
+
+ [[3]] {{{url_definitions_factory.html}Customizing <<<UrlDefinitionsFactory>>>}}.
Added: tiles/framework/trunk/src/site/apt/tutorial/extension/template.apt
URL: http://svn.apache.org/viewvc/tiles/framework/trunk/src/site/apt/tutorial/extension/template.apt?rev=774103&view=auto
==============================================================================
--- tiles/framework/trunk/src/site/apt/tutorial/extension/template.apt (added)
+++ tiles/framework/trunk/src/site/apt/tutorial/extension/template.apt Tue May 12 21:41:29 2009
@@ -0,0 +1,102 @@
+~~ $Id: index.apt 538978 2007-05-17 15:43:58Z apetrelli $
+~~
+~~ 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.
+~~
+ -----------
+ Supporting a template language
+ -----------
+
+Supporting a template language
+
+ Tiles currently uses JSP, FreeMarker and Velocity as a template language.
+ All these view technologies are supported through the
+ {{{../../framework/tiles-template}tiles-template}} module.
+
+ This module contains all the common code for directive-based template languages,
+ JSP and FreeMarker have this characteristic, because they use "tags" as directives.
+ Velocity support uses both a "directive-based" style and a Java-like style.
+
+* Creating directives
+
+ To create a directive in your favourite template language, simply use all of
+ the classes in <<<org.apache.tiles.template>>> package. These classes (called "models)
+ have three methods:
+
+ * <<<start>>>: to be called at the start of the directive;
+
+ * <<<end>>>: to be called at the end of the directive;
+
+ * <<<execute>>>: when you eed to use directives with and without body.
+
+ []
+
+ Typically, you need only to use <<<start>>> and <<<end>>> methods (this is the
+ case of JSP and FreeMarker), but sometimes you need <<<execute>>> to: Velocity
+ support uses <<<execute>>> methods to have a clearer syntax when no body is
+ provided.
+
+ For example, the {{{../../apidocs/org/apache/tiles/template/InsertAttributeModel.html}InsertAttributeModel}}
+ model can be implemented in FreeMarker this way:
+
+------------------------
+@SuppressWarnings("unchecked")
+public void execute(Environment env, Map params, TemplateModel[] loopVars,
+ TemplateDirectiveBody body) throws TemplateException, IOException {
+ Map<String, TemplateModel> parms = (Map<String, TemplateModel>) params;
+ TilesContainer container = FreeMarkerUtil.getCurrentContainer(env);
+ model.start(
+ FreeMarkerUtil.getComposeStack(env),
+ container,
+ FreeMarkerUtil.getAsBoolean(parms.get("ignore"), false),
+ FreeMarkerUtil.getAsString(parms.get("preparer")),
+ FreeMarkerUtil.getAsString(parms.get("role")),
+ FreeMarkerUtil.getAsObject(parms.get("defaultValue")),
+ FreeMarkerUtil.getAsString(parms
+ .get("defaultValueRole")), FreeMarkerUtil
+ .getAsString(parms.get("defaultValueType")),
+ FreeMarkerUtil.getAsString(parms.get("name")),
+ (Attribute) FreeMarkerUtil.getAsObject(parms
+ .get("value")), env);
+ FreeMarkerUtil.evaluateBody(body);
+ model.end(FreeMarkerUtil.getComposeStack(env), container,
+ FreeMarkerUtil.getAsBoolean(parms.get("ignore"), false), env);
+}
+------------------------
+
+ As you can see, the map of parameters at the call of the tag are converted into
+ parameters of the template model. In JSP, private fields would have become such
+ parameters.
+ The <<<FreeMarkerUtil.evaluateBody(body)>>> is used to evaluate the body, and all
+ of its tags, so the model can start and end correctly.
+
+** The role of the compose stack
+
+ In the previous code you may have noticed the "compose stack" parameter.
+ This stack is simply a Stack of objects that is used to store objects that
+ need to be composed between the start and the end of the model.
+
+ For example, if you use {{{../../apidocs/org/apache/tiles/template/DefinitionModel.html}DefinitionModel}},
+ the Definition object is created in <<<start>>> and pushed into the stack and it is retrieved
+ in <<<end>>>. Between these methods, other models, like PutAttributeModel, can
+ get it from the stack and modify it.
+
+* Developing attribute renderers
+
+ Template language files (for example ".ftl" files for FreeMarker, ".vm" for Velocity
+ can be rendered using specific servlets (respectively FreemarkerServlet
+ and VelocityViewServlet).
\ No newline at end of file
Modified: tiles/framework/trunk/src/site/apt/tutorial/integration/freemarker.apt
URL: http://svn.apache.org/viewvc/tiles/framework/trunk/src/site/apt/tutorial/integration/freemarker.apt?rev=774103&r1=774102&r2=774103&view=diff
==============================================================================
--- tiles/framework/trunk/src/site/apt/tutorial/integration/freemarker.apt (original)
+++ tiles/framework/trunk/src/site/apt/tutorial/integration/freemarker.apt Tue May 12 21:41:29 2009
@@ -25,18 +25,25 @@
{{{http://freemarker.sourceforge.net/}FreeMarker}} is a templating framework
that can be used as a replacement for JavaServer Pages (JSP). Tiles can be
- used with FreeMarker because FreeMarker templates can use JSP tag libraries.
+ used with FreeMarker through the use of Tiles FreeMarker package.
* Configuration
- To use JSP support in FreeMarker, add this piece of configuration
+ To use FreeMarker together with Tiles
+
+ * Add FreeMarker jars (tested with FreeMarker 2.3.15).
+
+ * Add <<<tiles-template-x.x.x.jar>>> and <<<tiles-freemarker-x.x.x.jar>>> files
+ to your application
+
+ * To access ".ftl" files from HTTP requests, add this piece of configuration in <<<web.xml>>>
(the parameters can be modified as needed).
----------------------------------
<servlet>
<servlet-name>freemarker</servlet-name>
- <servlet-class>freemarker.ext.servlet.FreemarkerServlet</servlet-class>
-
+ <servlet-class>org.apache.tiles.freemarker.servlet.TilesFreemarkerServlet</servlet-class>
+
<!-- FreemarkerServlet settings: -->
<init-param>
<param-name>TemplatePath</param-name>
@@ -50,7 +57,7 @@
<param-name>ContentType</param-name>
<param-value>text/html</param-value>
</init-param>
-
+
<!-- FreeMarker settings: -->
<init-param>
<param-name>template_update_delay</param-name>
@@ -64,16 +71,51 @@
<param-name>number_format</param-name>
<param-value>0.##########</param-value>
</init-param>
-
+
<load-on-startup>5</load-on-startup>
</servlet>
----------------------------------
+ * To access ".ftl" files as attributes, register FreeMarkerAttributeRenderer
+ this way (only available in a servlet environment):
+
+----------------------------------
+@Override
+protected void registerAttributeRenderers(
+ BasicRendererFactory rendererFactory, TilesApplicationContext applicationContext,
+ TilesRequestContextFactory contextFactory,
+ TilesContainer container, AttributeEvaluator evaluator) {
+ super.registerAttributeRenderers(rendererFactory, applicationContext, contextFactory,
+ container, evaluator);
+ FreeMarkerAttributeRenderer freemarkerRenderer = new FreeMarkerAttributeRenderer();
+ freemarkerRenderer.setApplicationContext(applicationContext);
+ freemarkerRenderer.setEvaluator(evaluator);
+ freemarkerRenderer.setRequestContextFactory(contextFactory);
+ freemarkerRenderer.setParameter("TemplatePath", "/");
+ freemarkerRenderer.setParameter("NoCache", "true");
+ freemarkerRenderer.setParameter("ContentType", "text/html");
+ freemarkerRenderer.setParameter("template_update_delay", "0");
+ freemarkerRenderer.setParameter("default_encoding", "ISO-8859-1");
+ freemarkerRenderer.setParameter("number_format", "0.##########");
+ freemarkerRenderer.commit();
+ rendererFactory.registerRenderer("freemarker", freemarkerRenderer);
+}
+----------------------------------
+
+ This way you can specify an attribute that is rendered directly using this syntax:
+
+----------------------------------
+<put-attribute name="myAttribute" value="/pages/myPage.ftl" type="freemarker" />
+----------------------------------
+
* Usage in FreeMarker templates
- To use Tiles JSP tag libraries in FreeMarker templates, add this line in
- every page that needs Tiles:
+ Tiles directives are available this way:
----------------------------------
-<#assign tiles=JspTaglibs["http://tiles.apache.org/tags-tiles"]>
+<@tiles.nameOfDirective>
+ Other stuff...
+</...@tiles.nameOfDirective>
----------------------------------
+
+ For details about directives see the {{{../../apidocs/index.html}Javadocs}}.
Added: tiles/framework/trunk/src/site/apt/tutorial/integration/velocity.apt
URL: http://svn.apache.org/viewvc/tiles/framework/trunk/src/site/apt/tutorial/integration/velocity.apt?rev=774103&view=auto
==============================================================================
--- tiles/framework/trunk/src/site/apt/tutorial/integration/velocity.apt (added)
+++ tiles/framework/trunk/src/site/apt/tutorial/integration/velocity.apt Tue May 12 21:41:29 2009
@@ -0,0 +1,126 @@
+~~ $Id: freemarker.apt 709153 2008-10-30 12:54:10Z apetrelli $
+~~
+~~ 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.
+~~
+ -----------
+ Integration with Apache Velocity
+ -----------
+
+Integration with Apache Velocity
+
+ {{{http://velocity.apache.org/}Apache Velocity}} is a templating framework
+ that can be used as a replacement for JavaServer Pages (JSP). Tiles can be
+ used with Velocity through the use of Tiles Velocity package.
+
+* Configuration
+
+ To use Velocity together with Tiles
+
+ * Add Velocity (1.7 or better) and Velocity Tools (2.0 or better) jars to your application.
+
+ * Add <<<tiles-template-x.x.x.jar>>> and <<<tiles-velocity-x.x.x.jar>>> files
+ to your application.
+
+ * To access ".vm" files from HTTP requests, add this piece of configuration in <<<web.xml>>>
+ (the parameters can be modified as needed).
+
+----------------------------------
+<servlet>
+ <servlet-name>velocity</servlet-name>
+ <servlet-class>org.apache.velocity.tools.view.VelocityViewServlet</servlet-class>
+
+ <init-param>
+ <param-name>org.apache.velocity.toolbox</param-name>
+ <param-value>/WEB-INF/tools.xml</param-value>
+ </init-param>
+
+ <init-param>
+ <param-name>org.apache.velocity.properties</param-name>
+ <param-value>/WEB-INF/velocity.properties</param-value>
+ </init-param>
+</servlet>
+----------------------------------
+
+ * To access ".vm" files as attributes, register VelocityAttributeRenderer
+ this way (only available in a servlet environment):
+
+----------------------------------
+@Override
+protected void registerAttributeRenderers(
+ BasicRendererFactory rendererFactory, TilesApplicationContext applicationContext,
+ TilesRequestContextFactory contextFactory,
+ TilesContainer container, AttributeEvaluator evaluator) {
+ super.registerAttributeRenderers(rendererFactory, applicationContext, contextFactory,
+ container, evaluator);
+
+ VelocityAttributeRenderer velocityRenderer = new VelocityAttributeRenderer();
+ velocityRenderer.setApplicationContext(applicationContext);
+ velocityRenderer.setEvaluator(evaluator);
+ velocityRenderer.setRequestContextFactory(contextFactory);
+ velocityRenderer.setParameter("org.apache.velocity.toolbox", "/WEB-INF/tools.xml");
+ velocityRenderer.setParameter("org.apache.velocity.properties", "/WEB-INF/velocity.properties");
+ velocityRenderer.commit();
+ rendererFactory.registerRenderer("velocity", velocityRenderer);
+}
+----------------------------------
+
+ This way you can specify an attribute that is rendered directly using this syntax:
+
+----------------------------------
+<put-attribute name="myAttribute" value="/pages/myPage.vm" type="velocity" />
+----------------------------------
+
+* Usage in Velocity templates
+
+ There are two Velocity tools that will be available to your application:
+
+ * the <<<tilesAlt>>> tool, that is a Velocity-style tool:
+
+----------------------------------
+$tilesAlt.startAttributeContext()
+$set($templateAttribute = $tilesAlt.createTemplateAttribute("/page/myTemplate.vm"))
+$set($attributeContext = $tilesAlt.getAttributeContext())
+ $set($attribute = $tilesAlt.createAttribute())
+ $attribute.setValue("This is the title.")
+ $attributeContext.putAttribute("title", $attribute})
+
+ $set($attribute = $tilesAlt.createAttribute())
+ $attribute.setValue("/velocity/header.vm")
+ $attribute.setRenderer("velocity")
+ $attributeContext.putAttribute("header", $attribute})
+
+ $set($attribute = $tilesAlt.createAttribute())
+ $attribute.setValue("/velocity/body.vm")
+ $attribute.setRenderer("velocity")
+ $attributeContext.putAttribute("body", $attribute})
+
+$tilesAlt.renderAttribute($templateAttribute)
+$tilesAlt.endAttributeContext()
+----------------------------------
+
+ * the <<<tiles>>> tool, that has both Velocity-style methods and directive oriented methods.
+
+----------------------------------
+$tiles.insertTemplate.start({"template":"/page/myTemplate.vm"})
+ $tiles.putAttribute({"name":"title", "value":"This is the title."})
+ $tiles.putAttribute({"name":"header", "value":"/velocity/header.vm", "type":"velocity"})
+ $tiles.putAttribute({"name":"body", "value":"/velocity/body.vm", "type":"velocity"})
+$tiles.insertTemplate().end()
+----------------------------------
+
+ For details about directives see the {{{../../apidocs/index.html}Javadocs}}.
Modified: tiles/framework/trunk/src/site/apt/tutorial/integration/view.apt
URL: http://svn.apache.org/viewvc/tiles/framework/trunk/src/site/apt/tutorial/integration/view.apt?rev=774103&r1=774102&r2=774103&view=diff
==============================================================================
--- tiles/framework/trunk/src/site/apt/tutorial/integration/view.apt (original)
+++ tiles/framework/trunk/src/site/apt/tutorial/integration/view.apt Tue May 12 21:41:29 2009
@@ -24,5 +24,8 @@
Integration with other View Technologies
Currently Tiles 2 is only integrated with JavaServer Pages but it can be used
- with {{{freemarker.html}FreeMarker}}.
- Hopefully it will {{{http://velocity.apache.org/}Velocity}}.
+ with:
+
+ * {{{freemarker.html}FreeMarker}}.
+
+ * {{{velocity.html}Velocity}}.
Modified: tiles/framework/trunk/src/site/site.xml
URL: http://svn.apache.org/viewvc/tiles/framework/trunk/src/site/site.xml?rev=774103&r1=774102&r2=774103&view=diff
==============================================================================
--- tiles/framework/trunk/src/site/site.xml (original)
+++ tiles/framework/trunk/src/site/site.xml Tue May 12 21:41:29 2009
@@ -52,115 +52,121 @@
href="security/index.html"/>
</menu>
<menu name="Documentation">
- <item
+ <item
name="What's new"
href="whats-new.html"/>
- <item
+ <item
name="Getting Started"
href="getting_started.html"/>
- <item
+ <item
name="Tutorial"
href="tutorial/index.html"
collapse="true">
- <item
+ <item
name="The composite view pattern"
href="tutorial/pattern.html"/>
- <item
+ <item
name="Configuration"
href="tutorial/configuration.html"/>
- <item
+ <item
name="Wildcards in configuration files"
href="tutorial/wildcard-configuration.html"/>
- <item
+ <item
name="Basic Usage"
href="tutorial/basic/index.html"
collapse="true">
- <item
+ <item
name="Tiles Concepts"
href="tutorial/basic/concepts.html"/>
- <item
+ <item
name="Creating Pages"
href="tutorial/basic/pages.html"/>
</item>
- <item
+ <item
name="Advanced Topics"
href="tutorial/advanced/index.html"
collapse="true">
- <item
+ <item
name="Nesting and Extending"
href="tutorial/advanced/nesting-extending.html"/>
- <item
+ <item
name="List Attributes"
href="tutorial/advanced/list-attributes.html"/>
- <item
+ <item
name="Runtime Composition"
href="tutorial/advanced/runtime.html"/>
- <item
+ <item
name="View Preparers"
href="tutorial/advanced/preparer.html"/>
- <item
+ <item
name="Rendering Utilities"
href="tutorial/advanced/utils.html"/>
- <item
+ <item
name="Localization"
href="tutorial/advanced/l10n.html"/>
- <item
+ <item
name="Using Beans as Attributes"
href="tutorial/advanced/beans.html"/>
- <item
+ <item
name="Menu-ing"
href="tutorial/advanced/menu.html"/>
- <item
+ <item
name="Wildcard support"
href="tutorial/advanced/wildcard.html"/>
- <item
+ <item
name="EL support"
href="tutorial/advanced/el-support.html"/>
- <item
+ <item
name="Attribute rendering"
href="tutorial/advanced/attribute-rendering.html"/>
- <item
+ <item
name="Multiple containers"
href="tutorial/advanced/multiple-containers.html"/>
- <item
+ <item
name="Security"
href="tutorial/advanced/security.html"/>
</item>
- <item
+ <item
name="Integrations"
href="tutorial/integration/index.html"
collapse="true">
- <item
+ <item
name="Frameworks"
href="tutorial/integration/frameworks.html"/>
- <item
+ <item
name="View technologies"
href="tutorial/integration/view.html">
- <item
+ <item
name="FreeMarker"
href="tutorial/integration/freemarker.html"/>
+ <item
+ name="Velocity"
+ href="tutorial/integration/velocity.html"/>
</item>
</item>
- <item
+ <item
name="Extensions"
href="tutorial/extension/index.html"
collapse="true">
- <item
+ <item
name="Extension Points"
href="tutorial/extension/points.html"/>
- <item
+ <item
+ name="Template languages"
+ href="tutorial/extension/template.html"/>
+ <item
name="UrlDefinitionsFactory"
href="tutorial/extension/url_definitions_factory.html"/>
</item>
- <item
+ <item
name="Migration from Struts Tiles"
href="migration/index.html"/>
</item>
- <item
+ <item
name="HOW-TOs"
href="how-to/index.html"
collapse="true">
- <item
+ <item
name="Loading definitions from a database"
href="how-to/definitions-db.html"/>
</item>