Google Git
Sign in
apache / struts-site / 3934264825d58c20e3df42bc34fbd081a7c615b5 / . / content / plugins / tiles / index.html
blob: f784c5d4e14990e9dd265c3e91d20b01491dc98e [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<meta name="Date-Revision-yyyymmdd" content="20140918"/>
<meta http-equiv="Content-Language" content="en"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Tiles Plugin</title>
<link href="//fonts.googleapis.com/css?family=Source+Sans+Pro:300,400,600,700,400italic,600italic,700italic" rel="stylesheet" type="text/css">
<link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
<link href="/css/main.css" rel="stylesheet">
<link href="/css/custom.css" rel="stylesheet">
<link href="/highlighter/github-theme.css" rel="stylesheet">
<script src="//code.jquery.com/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="/bootstrap/js/bootstrap.js"></script>
<script type="text/javascript" src="/js/community.js"></script>
</head>
<body>
<a href="http://github.com/apache/struts" class="github-ribbon">
<img style="position: absolute; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png" alt="Fork me on GitHub">
</a>
<header>
<nav>
<div role="navigation" class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" data-toggle="collapse" data-target="#struts-menu" class="navbar-toggle">
Menu
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a href="/index.html" class="navbar-brand logo"><img src="/img/struts-logo.svg"></a>
</div>
<div id="struts-menu" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Home<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/index.html">Welcome</a></li>
<li><a href="/download.cgi">Download</a></li>
<li><a href="/releases.html">Releases</a></li>
<li><a href="/announce.html">Announcements</a></li>
<li><a href="http://www.apache.org/licenses/">License</a></li>
<li><a href="https://www.apache.org/foundation/thanks.html">Thanks!</a></li>
<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
</ul>
</li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Support<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/mail.html">User Mailing List</a></li>
<li><a href="https://issues.apache.org/jira/browse/WW">Issue Tracker</a></li>
<li><a href="/security.html">Reporting Security Issues</a></li>
<li class="divider"></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/Migration+Guide">Version Notes</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/Security+Bulletins">Security Bulletins</a></li>
<li class="divider"></li>
<li><a href="/maven/project-info.html">Maven Project Info</a></li>
<li><a href="/maven/struts2-core/dependencies.html">Struts Core Dependencies</a></li>
<li><a href="/maven/struts2-plugins/modules.html">Plugin Dependencies</a></li>
</ul>
</li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Documentation<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/birdseye.html">Birds Eye</a></li>
<li><a href="/primer.html">Key Technologies</a></li>
<li><a href="/kickstart.html">Kickstart FAQ</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/Home">Wiki</a></li>
<li class="divider"></li>
<li><a href="/getting-started/">Getting Started</a></li>
<li><a href="/security/">Security Guide</a></li>
<li><a href="/core-developers/">Core Developers Guide</a></li>
<li><a href="/tag-developers/">Tag Developers Guide</a></li>
<li><a href="/maven-archetypes/">Maven Archetypes</a></li>
<li><a href="/plugins/">Plugins</a></li>
<li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li>
<li><a href="/tag-developers/tag-reference.html">Tag reference</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/FAQs">FAQs</a></li>
<li><a href="http://cwiki.apache.org/S2PLUGINS/home.html">Plugin registry</a></li>
</ul>
</li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Contributing<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/youatstruts.html">You at Struts</a></li>
<li><a href="/helping.html">How to Help FAQ</a></li>
<li><a href="/dev-mail.html">Development Lists</a></li>
<li><a href="/contributors/">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/submitting-patches.html">Submitting patches</a></li>
<li><a href="/builds.html">Source Code and Builds</a></li>
<li><a href="/coding-standards.html">Coding standards</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/Contributors+Guide">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/release-guidelines.html">Release Guidelines</a></li>
<li><a href="/bylaws.html">PMC Charter</a></li>
<li><a href="/volunteers.html">Volunteers</a></li>
<li><a href="https://gitbox.apache.org/repos/asf?p=struts.git">Source Repository</a></li>
<li><a href="/updating-website.html">Updating the website</a></li>
</ul>
</li>
<li class="apache"><a href="http://www.apache.org/"><img src="/img/apache.png"></a></li>
</ul>
</div>
</div>
</div>
</nav>
</header>
<article class="container">
<section class="col-md-12">
<a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/plugins/tiles/index.md" title="Edit this page on GitHub">Edit on GitHub</a>
<a href="../" title="back to Plugins"><< back to Plugins</a>
<h1 class="no_toc" id="tiles-plugin">Tiles Plugin</h1>
<ul id="markdown-toc">
<li><a href="#features" id="markdown-toc-features">Features</a></li>
<li><a href="#usage" id="markdown-toc-usage">Usage</a> <ul>
<li><a href="#accessing-struts-attributes" id="markdown-toc-accessing-struts-attributes">Accessing Struts attributes</a></li>
<li><a href="#i18n" id="markdown-toc-i18n">I18N</a></li>
</ul>
</li>
<li><a href="#example" id="markdown-toc-example">Example</a></li>
<li><a href="#settings" id="markdown-toc-settings">Settings</a></li>
<li><a href="#installation" id="markdown-toc-installation">Installation</a></li>
</ul>
<p>Tiles is a templating framework designed to easily allow the creation of web application pages with a consistent look and feel. It can
be used for both page decorating and componentization.</p>
<p>The Tiles plugin allows actions to return Tiles pages.</p>
<h2 id="features">Features</h2>
<ul>
<li>Supports Tiles in Freemarker, JSP, and Velocity</li>
<li>Provides annotations to keep tiles.xml short and put definitons into actions</li>
</ul>
<h2 id="usage">Usage</h2>
<p>The following steps must be taken in order to enable tiles support within your Struts2 application:</p>
<ol>
<li>Include the struts-tiles-plugin as a dependency in your web application. If you are using maven2, the dependency configuration will
be similar to:</li>
</ol>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;dependency&gt;</span>
<span class="nt">&lt;groupId&gt;</span>org.apache.struts<span class="nt">&lt;/groupId&gt;</span>
<span class="nt">&lt;artifactId&gt;</span>struts2-tiles-plugin<span class="nt">&lt;/artifactId&gt;</span>
<span class="nt">&lt;version&gt;</span>${version.tiles}<span class="nt">&lt;/version&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
</code></pre></div></div>
<ol>
<li>Register the tiles listener. This listener will typically either be the standard tiles listener <code class="highlighter-rouge">org.apache.tiles.listener.TilesListener</code>
or the Struts2 replacement <code class="highlighter-rouge">org.apache.struts2.tiles.TilesListener</code>. The latter provides tighter integration with Struts features such
as freemarker integration.</li>
</ol>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;listener&gt;</span>
<span class="nt">&lt;listener-class&gt;</span>org.apache.struts2.tiles.StrutsTilesListener<span class="nt">&lt;/listener-class&gt;</span>
<span class="nt">&lt;/listener&gt;</span>
</code></pre></div></div>
<ol>
<li>All package definitions which require tiles support must either extend the <code class="highlighter-rouge">tiles-default</code> package or must register
the [Tiles Result] type definition.</li>
</ol>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;result-types&gt;</span>
<span class="nt">&lt;result-type</span> <span class="na">name=</span><span class="s">"tiles"</span> <span class="na">class=</span><span class="s">"org.apache.struts2.views.tiles.TilesResult"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/result-types&gt;</span>
</code></pre></div></div>
<ol>
<li>Configure your actions to utilize a tiles definition:</li>
</ol>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;action</span> <span class="na">name=</span><span class="s">"sample"</span> <span class="na">class=</span><span class="s">"org.apache.struts2.tiles.example.SampleAction"</span> <span class="nt">&gt;</span>
<span class="nt">&lt;result</span> <span class="na">name=</span><span class="s">"success"</span> <span class="na">type=</span><span class="s">"tiles"</span><span class="nt">&gt;</span>tilesWorks<span class="nt">&lt;/result&gt;</span>
<span class="nt">&lt;/action&gt;</span>
</code></pre></div></div>
<ol>
<li>Instead of xml configuration you can use annotations</li>
</ol>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nd">@Result</span><span class="o">(</span><span class="n">name</span> <span class="o">=</span> <span class="s">"success"</span><span class="o">,</span> <span class="n">type</span><span class="o">=</span><span class="s">"tiles"</span><span class="o">)</span>
<span class="nd">@TilesDefinition</span><span class="o">(</span><span class="n">extend</span> <span class="o">=</span> <span class="s">"fooLayout"</span><span class="o">,</span> <span class="n">putAttributes</span> <span class="o">=</span> <span class="o">{</span>
<span class="nd">@TilesPutAttribute</span><span class="o">(</span><span class="n">name</span> <span class="o">=</span> <span class="s">"header"</span><span class="o">,</span> <span class="n">value</span> <span class="o">=</span> <span class="s">"/WEB-INF/tiles/header.jsp"</span><span class="o">),</span>
<span class="nd">@TilesPutAttribute</span><span class="o">(</span><span class="n">name</span> <span class="o">=</span> <span class="s">"body"</span><span class="o">,</span> <span class="n">value</span> <span class="o">=</span> <span class="s">"/WEB-INF/tiles/body.ftl"</span><span class="o">)</span>
<span class="o">})</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">FooAction</span> <span class="kd">extends</span> <span class="n">ActionSupport</span> <span class="o">{</span>
</code></pre></div></div>
<ol>
<li>You have to define Tiles Definitons in a <code class="highlighter-rouge">tiles.xml</code> file. That can be placed in <code class="highlighter-rouge">resources</code> or in <code class="highlighter-rouge">WEB-INF</code>.</li>
</ol>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;!DOCTYPE tiles-definitions PUBLIC
"-//Apache Software Foundation//DTD Tiles Configuration 3.0//EN"
"http://tiles.apache.org/dtds/tiles-config_3_0.dtd"&gt;</span>
<span class="nt">&lt;tiles-definitions&gt;</span>
<span class="nt">&lt;definition</span> <span class="na">name=</span><span class="s">"fooLayout"</span> <span class="na">template=</span><span class="s">"/WEB-INF/tiles/layout.jsp"</span><span class="nt">&gt;</span>
<span class="nt">&lt;put-attribute</span> <span class="na">name=</span><span class="s">"title"</span> <span class="na">value=</span><span class="s">"Tiles Sample"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;put-attribute</span> <span class="na">name=</span><span class="s">"header"</span> <span class="na">value=</span><span class="s">".header"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;put-attribute</span> <span class="na">name=</span><span class="s">"body"</span> <span class="na">value=</span><span class="s">".bodyp"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/definition&gt;</span>
<span class="nt">&lt;definition</span> <span class="na">name=</span><span class="s">"tilesWorks"</span> <span class="na">extends=</span><span class="s">"fooLayout"</span><span class="nt">&gt;</span>
<span class="nt">&lt;put-attribute</span> <span class="na">name=</span><span class="s">"header"</span> <span class="na">value=</span><span class="s">"/WEB-INF/tiles/header.jsp"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;put-attribute</span> <span class="na">name=</span><span class="s">"body"</span> <span class="na">value=</span><span class="s">"/WEB-INF/tiles/body.jsp"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/definition&gt;</span>
<span class="nt">&lt;/tiles-definitions&gt;</span>
</code></pre></div></div>
<p>As from Struts 2.3.28, the plugin automatically loads all Tiles definitions matching the following pattern <code class="highlighter-rouge">tiles*.xml</code> - you don’t have
to specify them via <code class="highlighter-rouge">org.apache.tiles.definition.DefinitionsFactory.DEFINITIONS_CONFIG</code> in <code class="highlighter-rouge">web.xml</code>, but you can use this option if your
application is going to work in restricted servlet environment e.g. Google AppEngine. In such case, definitions will be read from
the provided init-param.</p>
<blockquote>
<p>Note: When using a Tomcat WAR versoning mechanism which uses <code class="highlighter-rouge">##</code> you must specify all the tiles definition directly using
the <code class="highlighter-rouge">init-param</code>, in other case it won’t be loaded. It’s due to limitation of <code class="highlighter-rouge">URL</code> class.</p>
</blockquote>
<h3 id="accessing-struts-attributes">Accessing Struts attributes</h3>
<p>As from Struts version 2.5.3 it’s possible accessing defined values on a <code class="highlighter-rouge">ValueStack</code> using <code class="highlighter-rouge">S2</code> prefix when defining an expression
in tiles definition, e.g.:</p>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;definition</span> <span class="na">name=</span><span class="s">"home"</span> <span class="na">extends=</span><span class="s">"logged-in"</span><span class="nt">&gt;</span>
<span class="nt">&lt;put-attribute</span> <span class="na">name=</span><span class="s">"title"</span> <span class="na">expression=</span><span class="s">"S2:actionProperty"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;put-attribute</span> <span class="na">name=</span><span class="s">"body"</span> <span class="na">value=</span><span class="s">"/WEB-INF/tiles/home.jsp"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/definition&gt;</span>
</code></pre></div></div>
<p>In such case Tiles will delegate evaluation of the expression to Struts and <code class="highlighter-rouge">ValueStack</code> will be examined to evaluate the expression.</p>
<h3 id="i18n">I18N</h3>
<p>Instead of defining new tiles definitions per supported language (i.e.: <code class="highlighter-rouge">tiles.xml</code>, <code class="highlighter-rouge">tiles_de.xml</code>, <code class="highlighter-rouge">tiles_pl.xml</code>) you can use <code class="highlighter-rouge">I18N</code>
prefix to evaluate provided expression as a key in Struts resource bundles. </p>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;definition</span> <span class="na">name=</span><span class="s">"home"</span> <span class="na">extends=</span><span class="s">"logged-in"</span><span class="nt">&gt;</span>
<span class="nt">&lt;put-attribute</span> <span class="na">name=</span><span class="s">"title"</span> <span class="na">expression=</span><span class="s">"I18N:home.title"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;put-attribute</span> <span class="na">name=</span><span class="s">"body"</span> <span class="na">value=</span><span class="s">"/WEB-INF/tiles/home.jsp"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/definition&gt;</span>
</code></pre></div></div>
<h2 id="example">Example</h2>
<p>This example shows a Tiles layout page using Struts tags:</p>
<pre><code class="language-jsp">&lt;%@ taglib uri="http://tiles.apache.org/tags-tiles" prefix="tiles" %&gt;
&lt;%@ taglib prefix="s" uri="/struts-tags" %&gt;
&lt;%-- Show usage; Used in Header --%&gt;
&lt;tiles:importAttribute name="title" scope="request"/&gt;
&lt;html&gt;
&lt;head&gt;&lt;title&gt;Struts2 Showcase - &lt;tiles:getAsString name="title"/&gt;&lt;/title&gt;&lt;/head&gt;
&lt;body&gt;
&lt;tiles:insertAttribute name="header"/&gt;
&lt;tiles:insertAttribute name="body"/&gt;
&lt;p&gt;Notice that this is a layout made in JSP&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;
</code></pre>
<p>Please check <a href="https://github.com/apache/struts-examples/tree/master/tiles">tiles</a> example in <a href="https://github.com/apache/struts-examples/tree/master/tiles">struts-examples</a> project.</p>
<h2 id="settings">Settings</h2>
<p>This plugin does inherits settings from <a href="http://tiles.apache.org/config-reference.html">Tiles configuration</a>.</p>
<h2 id="installation">Installation</h2>
<p>This plugin can be installed by copying the plugin jar into your application’s <code class="highlighter-rouge">/WEB-INF/lib</code> directory. No other files need to be copied or created.</p>
</section>
</article>
<footer class="container">
<div class="col-md-12">
Copyright &copy; 2000-2018 <a href="http://www.apache.org/">The Apache Software Foundation </a>.
All Rights Reserved.
</div>
<div class="col-md-12">
Apache Struts, Struts, Apache, the Apache feather logo, and the Apache Struts project logos are
trademarks of The Apache Software Foundation.
</div>
<div class="col-md-12">Logo and website design donated by <a href="https://softwaremill.com/">SoftwareMill</a>.</div>
</footer>
<script>!function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (!d.getElementById(id)) {
js = d.createElement(s);
js.id = id;
js.src = "//platform.twitter.com/widgets.js";
fjs.parentNode.insertBefore(js, fjs);
}
}(document, "script", "twitter-wjs");</script>
<script src="https://apis.google.com/js/platform.js" async="async" defer="defer"></script>
<div id="fb-root"></div>
<script>(function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s);
js.id = id;
js.src = "//connect.facebook.net/en_GB/all.js#xfbml=1";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>
</body>
</html>