blob: 53bcb62e86de803c77a216f7247fb75cab5a90c5 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<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">
<link href="//,400,600,700,400italic,600italic,700italic" rel="stylesheet" type="text/css">
<link href="//" 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="//"></script>
<script type="text/javascript" src="/bootstrap/js/bootstrap.js"></script>
<script type="text/javascript" src="/js/community.js"></script>
<a href="" class="github-ribbon">
<img style="position: absolute; right: 0; border: 0;" src="" alt="Fork me on GitHub">
<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">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<a href="/index.html" class="navbar-brand logo"><img src="/img/struts-logo.svg"></a>
<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>
<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-2021.html">Announcements</a></li>
<li><a href="">License</a></li>
<li><a href="">Thanks!</a></li>
<li><a href="">Sponsorship</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Support<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/mail.html">User Mailing List</a></li>
<li><a href="">Issue Tracker</a></li>
<li><a href="/security.html">Reporting Security Issues</a></li>
<li class="divider"></li>
<li><a href="">Version Notes</a></li>
<li><a href="">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>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Documentation<b class="caret"></b>
<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="">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="">FAQs</a></li>
<li><a href="">Plugin registry</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Contributing<b class="caret"></b>
<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="">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="">Source Repository</a></li>
<li><a href="/updating-website.html">Updating the website</a></li>
<li class="apache"><a href=""><img src="/img/apache.png"></a></li>
<article class="container">
<section class="col-md-12">
<a class="edit-on-gh" href="" title="Edit this page on GitHub">Edit on GitHub</a>
<a href="index.html" title="back to Getting started"><< back to Getting started</a>
<h1 class="no_toc" id="themes">Themes</h1>
<ul id="markdown-toc">
<li><a href="#introduction" id="markdown-toc-introduction">Introduction</a></li>
<li><a href="#specifying-the-theme-struts-2-should-use" id="markdown-toc-specifying-the-theme-struts-2-should-use">Specifying The Theme Struts 2 Should Use</a></li>
<li><a href="#specifying-the-css-used-by-the-struts-2-tag" id="markdown-toc-specifying-the-css-used-by-the-struts-2-tag">Specifying The CSS Used By The Struts 2 Tag</a></li>
<li><a href="#creating-and-applying-your-own-themes-for-struts-2-tags" id="markdown-toc-creating-and-applying-your-own-themes-for-struts-2-tags">Creating And Applying Your Own Themes For Struts 2 Tags</a></li>
<li><a href="#summary" id="markdown-toc-summary">Summary</a></li>
<p>The example code for this tutorial, <strong>themes</strong>, is available for checkout at <a href="">struts-examples</a></p>
<h2 id="introduction">Introduction</h2>
<p>When you use a Struts 2 tag such as <code class="highlighter-rouge">s:select</code> in your web page, the Struts 2 framework generates HTML that styles
the appearance and controls the layout of the select control. The style and layout is determined by which Struts 2 theme
is set for the tag. Struts 2 comes with three built-in themes: <code class="highlighter-rouge">simple</code>, <code class="highlighter-rouge">xhtml</code>, and <code class="highlighter-rouge">css_xhtml</code>. If you don’t specify
a theme, then Struts 2 will use the <code class="highlighter-rouge">xhtml</code> theme by default.</p>
<p>The <a href="">Struts 2 user mailing list</a> is an excellent place to get help. If you are having
a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don’t find an answer
to your problem, post a question on the mailing list.</p>
<p>For example, this Struts 2 select tag:</p>
<p><strong>Struts 2 Select Tag</strong></p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;s:select</span> <span class="na">key=</span><span class="s">""</span> <span class="na">list=</span><span class="s">"sports"</span> <span class="nt">/&gt;</span>
<p>generates this HTML markup:</p>
<p><strong>HTML Created By Struts 2 Select Tag</strong></p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;tr&gt;</span>
<span class="nt">&lt;td</span> <span class="na">class=</span><span class="s">"tdLabel"</span><span class="nt">&gt;</span>
<span class="nt">&lt;label</span> <span class="na">for=</span><span class="s">"save_personBean_sport"</span> <span class="na">class=</span><span class="s">"label"</span><span class="nt">&gt;</span>Favorite sport:<span class="nt">&lt;/label&gt;</span>
<span class="nt">&lt;/td&gt;</span>
<span class="nt">&lt;td&gt;</span>
<span class="nt">&lt;select</span> <span class="na">name=</span><span class="s">""</span> <span class="na">id=</span><span class="s">"save_personBean_sport"</span><span class="nt">&gt;</span>
<span class="nt">&lt;option</span> <span class="na">value=</span><span class="s">"football"</span><span class="nt">&gt;</span>football<span class="nt">&lt;/option&gt;</span>
<span class="nt">&lt;option</span> <span class="na">value=</span><span class="s">"baseball"</span><span class="nt">&gt;</span>baseball<span class="nt">&lt;/option&gt;</span>
<span class="nt">&lt;option</span> <span class="na">value=</span><span class="s">"basketball"</span> <span class="na">selected=</span><span class="s">"selected"</span><span class="nt">&gt;</span>basketball<span class="nt">&lt;/option&gt;</span>
<span class="nt">&lt;/select&gt;</span>
<span class="nt">&lt;/td&gt;</span>
<span class="nt">&lt;/tr&gt;</span>
<p>Notice how the HTML generated uses table tags to control the layout of the label and select HTML. There is also a class,
<code class="highlighter-rouge">tdLabel</code>, applied to the table column where the label tag is rendered. Since no theme was specified for the Struts 2
select tag the default <code class="highlighter-rouge">xhmtl</code> theme was used.</p>
<h2 id="specifying-the-theme-struts-2-should-use">Specifying The Theme Struts 2 Should Use</h2>
<p>The Struts 2 tags have a theme attribute you can use to specify which Struts 2 theme should be used when creating the HTML
for that tag. The values for the theme attribute are <code class="highlighter-rouge">simple</code>, <code class="highlighter-rouge">xhtml</code>, <code class="highlighter-rouge">css_xhtml</code>, and <code class="highlighter-rouge">ajax</code>. To learn more about these themes
visit <a href="../tag-developers/themes-and-templates.html">Themes and Templates Documentation</a>. This tutorial will review
the <code class="highlighter-rouge">xhtml</code>, <code class="highlighter-rouge">css_xhtml</code>, and the <code class="highlighter-rouge">simple</code> themes. The <code class="highlighter-rouge">ajax</code> theme is a special theme used for ajax operations
(see <a href="../tag-developers/ajax-theme.html">Ajax Theme in the documentation</a>).</p>
<p>You can specify the theme on a per Struts 2 tag basis or you can use one of the following methods to specify what theme
Struts 2 should use:</p>
<li>The <code class="highlighter-rouge">theme</code> attribute on the specific tag</li>
<li>The <code class="highlighter-rouge">theme</code> attribute on a tag’s surrounding form tag</li>
<li>The page-scoped attribute named <code class="highlighter-rouge">theme</code></li>
<li>The request-scoped attribute named <code class="highlighter-rouge">theme</code></li>
<li>The session-scoped attribute named <code class="highlighter-rouge">theme</code></li>
<li>The application-scoped attribute named <code class="highlighter-rouge">theme</code></li>
<li>The <code class="highlighter-rouge">struts.ui.theme</code> constant in <code class="highlighter-rouge">struts.xml</code> (defaults to <code class="highlighter-rouge">xhtml</code>)</li>
<p>Consult <a href="../tag-developers/selecting-themes.html">Selecting Themes</a> for how to set the theme using the above approaches.</p>
<p>In the example application, examine <code class="highlighter-rouge">edit.jsp</code>. The theme attribute of the form tag is set to <code class="highlighter-rouge">xhtml</code>. Run the application
(see the readme.txt file) and view the source for edit.jsp after it is rendered in your browser. You should see the form
HTML tags layout controlled by table tags.</p>
<p>Change the theme to <code class="highlighter-rouge">simple</code> for the form’s theme attribute and redeploy the application. Examine the source for <code class="highlighter-rouge">edit.jsp</code>
after it is rendered in the browser. You should see that there are no table tags controlling the layout and also there
are no label tags for the text fields.</p>
<p>Change the theme to <code class="highlighter-rouge">css_xhtml</code> for the form’s theme attribute and redeploy the application. Examine the source for <code class="highlighter-rouge">edit.jsp</code>
after it is rendered in the browser. The layout of the form tags is now controlled by div tags and the label tags are back.</p>
<h2 id="specifying-the-css-used-by-the-struts-2-tag">Specifying The CSS Used By The Struts 2 Tag</h2>
<p>Change the theme attribute for the form tag back to xhtml. Notice when you view the source of edit.jsp after it is rendered
in the browser that there is a class named tdLabel applied to the table column that contains the label. This CSS class
controls the position of the label in the table column. The tdLabel style is defined in <code class="highlighter-rouge">/themes/struts/xhtml/styles.css</code>.
The link to this style sheet was included in edit.jsp’s head section when you add the <code class="highlighter-rouge">s:head</code> tag to <code class="highlighter-rouge">edit.jsp</code>.</p>
<p>Load this style sheet in your browser (in the example application the link is <a href="http://localhost:8080/themes/struts/xhtml/styles.css">http://localhost:8080/themes/struts/xhtml/styles.css</a>
if your Servlet container is running on localhost, port 8080). You’ll see the following:</p>
<div class="language-css highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nc">.label</span> <span class="p">{</span><span class="nl">font-style</span><span class="p">:</span><span class="nb">italic</span><span class="p">;</span> <span class="p">}</span>
<span class="nc">.errorLabel</span> <span class="p">{</span><span class="nl">font-style</span><span class="p">:</span><span class="nb">italic</span><span class="p">;</span> <span class="nl">color</span><span class="p">:</span><span class="no">red</span><span class="p">;</span> <span class="p">}</span>
<span class="nc">.errorMessage</span> <span class="p">{</span><span class="nl">font-weight</span><span class="p">:</span><span class="nb">bold</span><span class="p">;</span> <span class="nl">color</span><span class="p">:</span><span class="no">red</span><span class="p">;</span> <span class="p">}</span>
<span class="nc">.checkboxLabel</span> <span class="p">{}</span>
<span class="nc">.checkboxErrorLabel</span> <span class="p">{</span><span class="nl">color</span><span class="p">:</span><span class="no">red</span><span class="p">;</span> <span class="p">}</span>
<span class="nc">.required</span> <span class="p">{</span><span class="nl">color</span><span class="p">:</span><span class="no">red</span><span class="p">;}</span>
<span class="nc">.tdLabel</span> <span class="p">{</span><span class="nl">text-align</span><span class="p">:</span><span class="nb">right</span><span class="p">;</span> <span class="nl">vertical-align</span><span class="p">:</span><span class="nb">top</span><span class="p">;</span> <span class="p">}</span>
<p>So the .label selector renders the label tag’s text in italic. The .tdLabel tag specifies that the text should align
to the right and top of the table column.</p>
<p>You can override the above selectors by including the same selectors in your page’s head section. For example add
the following to the head section of <code class="highlighter-rouge">edit.jsp</code>.</p>
<p><strong>Override Label Style</strong></p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;style </span><span class="na">type=</span><span class="s">"text/css"</span><span class="nt">&gt;</span>
<span class="nc">.label</span> <span class="p">{</span><span class="nl">color</span><span class="p">:</span><span class="no">blue</span><span class="p">;</span> <span class="nl">font-style</span><span class="p">:</span><span class="nb">normal</span><span class="p">;</span> <span class="nl">font-weight</span><span class="p">:</span><span class="nb">bold</span><span class="p">}</span>
<span class="nt">&lt;/style&gt;</span>
<p>Now the label tag will render the text in blue, bold, normal (not italics) style.</p>
<h2 id="creating-and-applying-your-own-themes-for-struts-2-tags">Creating And Applying Your Own Themes For Struts 2 Tags</h2>
<p>The theme templates (simple, xhtml, css_xhtml) can be found in the Struts 2 core jar file. If you expand (extract the files)
the Struts 2 core jar file you’ll find folders named <code class="highlighter-rouge">template.css_xhtml</code>, <code class="highlighter-rouge">template.simple</code>, and <code class="highlighter-rouge">template.xhtml</code>.
Those folders contain the templates for the three default Struts 2 themes. In each folder is a file for each Struts 2 tag.
For example if you expand the <code class="highlighter-rouge">template.xhtml</code> folder you’ll see the <code class="highlighter-rouge">select.ftl</code> file.</p>
<p>The Struts 2 framework uses the FreeMarker template engine to generate the HTML for the Struts 2 tags. That’s why the file
extension is <code class="highlighter-rouge">.ftl</code>. You can learn more about FreeMarker by visiting <a href=""></a>.</p>
<p>Also in the <code class="highlighter-rouge">template.xhmtl</code> folder is the <code class="highlighter-rouge">styles.css</code> file. This is the <code class="highlighter-rouge">styles.css</code> file that your application will use
if it uses the <code class="highlighter-rouge">xhtml</code> theme.</p>
<p>Let’s say we wanted to create our own theme that will change how the Struts 2 checkboxlist tag displays the checkboxes
and their labels.</p>
<p>In the example application I’ve extended the default XHMTL theme (see file <code class="highlighter-rouge"></code> under <code class="highlighter-rouge">src/main/resources/template/KUTheme</code>).
The <code class="highlighter-rouge">checkboxlist.ftl</code> theme that is part of the XHTML theme only includes a space between each label and the next checkbox
(see <code class="highlighter-rouge">checkboxlist.ftl</code> in the <code class="highlighter-rouge">template/simple</code> folder in Struts 2 core). That is why all the checkboxes are displayed
across the width of the browser window. For my custom checkboxlist theme I want to have a break tag after each label tag
so that each checkbox and its label will be on their own line.</p>
<p>In the example application there is a folder named <code class="highlighter-rouge">src/main/resources/template/KUTheme</code>. In that folder is a <code class="highlighter-rouge">checkboxlist.ftl</code>,
the contents of which I originally copied from the <code class="highlighter-rouge">checkboxlist.ftl</code> that is in the <code class="highlighter-rouge">templates.xhtml</code> folder from
the Struts 2 core jar.</p>
<p>I then modified the <code class="highlighter-rouge">checkboxlist.ftl</code> in the KUTheme folder to be:</p>
<p><strong>Modified checkboxlist.ftl</strong></p>
<pre><code class="language-ftl">&lt;#include "/${parameters.templateDir}/${parameters.expandTheme}/controlheader.ftl" /&gt;
&lt;#include "/${parameters.templateDir}/KUTheme_simple/checkboxlist.ftl" /&gt;
&lt;#include "/${parameters.templateDir}/${parameters.expandTheme}/controlfooter.ftl" /&gt;&lt;#nt/&gt;
<p>Be sure to note the change to the second line—using KUTheme_simple in the path.</p>
<p>Then in the example application I created a KUTheme_simple folder under <code class="highlighter-rouge">src/main/resources/template</code> (optionally you
can place it under <code class="highlighter-rouge">webapp</code>, e.g. <code class="highlighter-rouge">src/main/webapp/template</code> ). In that folder I created <code class="highlighter-rouge">checkboxlist.ftl</code> and copied
the contents from <code class="highlighter-rouge">template.simple</code> <code class="highlighter-rouge">checkboxlist.ftl</code> (again found in the Struts 2 core jar). After copying the contents
to <code class="highlighter-rouge">checkboxlist.ftl</code> that is in <code class="highlighter-rouge">KUTheme_simple</code> folder, I modified <code class="highlighter-rouge">checkboxlist.ftl</code> so that the label tag has a style
of red bold text and I added a break tag after each label so that each check box and label will be on its own line.</p>
<p>Since the XHTML theme is the default theme and I have a <code class="highlighter-rouge"></code> file defined with <code class="highlighter-rouge">parent = xhtml</code>,
the KUTheme will inherit all the themes from xhmtl except for the theme for the checkboxlist tag since my KUTheme includes
a definition for that tag’s layout. In the <code class="highlighter-rouge">struts.xml</code> file (<code class="highlighter-rouge">src/main/resources</code>) you will see that the I’ve specified
the default theme to be KUTheme.</p>
<p>In the deployed web application, Struts 2 will first look for a tag’s template on the application’s class path and if it
doesn’t find the template there it will use the default template that is part of the Struts 2 core jar. Since we’ve
added a template folder to the application’s web root, now when Struts 2 creates the HTML to display the checkboxlist
tag it will use the template that is in the KUTheme folder (which tells it to use the <code class="highlighter-rouge">checkboxlist.ftl</code> file that is
in the KUTheme_simple folder instead of the one in the <code class="highlighter-rouge">template.simple</code> folder that is part of the Struts 2 core Jar).</p>
<p>After redeploying the application the check boxes for the Car Models Owned should appear like:</p>
<p><img src="attachments/att23527657_Screen shot 2010-09-11 at 12.37.12 PM.png" alt="Screen shot 2010-09-11 at 12.37.12 PM.png" /></p>
<h2 id="summary">Summary</h2>
<p>You can easily override the default theme used by Struts 2 to control the appearance and layout of a Struts 2 tag. Each
Struts 2 tag has an associated template file (e.g. <code class="highlighter-rouge">select.ftl</code>) that is in a folder named after the theme (e.g. xhtml).
By default the Struts framework will look in the Struts 2 core Jar file for the theme folder and templates. However,
if you include your own theme folder (e.g. KUTheme) under webapp/template (or WebContent/template in the Ant version)
and specify that folder name (e.g. KUTheme) as the value for the theme attribute, then the Struts 2 framework will look
in that theme folder for the tag’s template.</p>
<p>To learn more about how to use the Struts 2 themes and how you can override them, visit <a href="../tag-developers/themes-and-templates.html">Themes and Templates Documentation</a> .</p>
<td>Return to <a href="wildcard-method-selection.html">Wildcard method selection</a></td>
<td>onward to <a href="spring.html">Spring and Struts 2</a></td>
<footer class="container">
<div class="col-md-12">
Copyright &copy; 2000-2018 <a href="">The Apache Software Foundation </a>.
All Rights Reserved.
<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 class="col-md-12">Logo and website design donated by <a href="">SoftwareMill</a>.</div>
<script>!function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (!d.getElementById(id)) {
js = d.createElement(s); = id;
js.src = "//";
fjs.parentNode.insertBefore(js, fjs);
}(document, "script", "twitter-wjs");</script>
<script src="" 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); = id;
js.src = "//";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>