Page History

Introduction

When you use a Struts 2 tag such as s:select 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: simple, xhtml, and css_xhtml. If you don’t specify a theme, then Struts 2 will use the xhtml theme by default.

...

For example, this Struts 2 select tag:

<s:select key="personBean.sport" list="sports" />

generates this HTML markup:

<tr>
<td class="tdLabel">
<label for="save_personBean_sport" class="label">Favorite sport:</label>
</td>
<td>
<select name="personBean.sport" id="save_personBean_sport">
    <option value="football">football</option>
    <option value="baseball">baseball</option>
    <option value="basketball" selected="selected">basketball</option>
</select>
</td>
</tr>

Notice how the HTML generated uses table tags to control the layout of the label and select HTML. There is also a class, tdLabel, applied to the table column where the label tag is rendered. Since no theme was specified for the Struts 2 select tag the default xhmtl theme was used.

...

Load this style sheet in your browser (in the example application the link is http://localhost:8080/themes/struts/xhtml/styles.css^{Image Removed} if your Servlet container is running on localhost, port 8080). You’ll see the following:

.label {font-style:italic; }
.errorLabel {font-style:italic; color:red; }
.errorMessage {font-weight:bold; color:red; }
.checkboxLabel {}
.checkboxErrorLabel {color:red; }
.required {color:red;}
.tdLabel {text-align:right; vertical-align:top; }

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.

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 edit.jsp.

<style type="text/css">
  .label {color:blue; font-style:normal; font-weight:bold}
</style>

Now the label tag will render the text in blue, bold, normal (not italics) style.

...

In the example application I've specified that the form tag should use the xhtml extended the default XHMTL theme (see edit.jsp). The xhtml theme templates for the tags are in the template.xhtml folder (in the Struts 2 core jar file). The template for the Struts 2 checkboxlist tag is appropriately named checkboxlist.ftl. Opening that file you'll see that includes the checkboxlist template that is in the template.simple folder (the xhtml templates extend the templates defined in the template.simple folder). Opening the checkboxlist.ftl file in the template.simple folder, you'll see that there is only file theme.properties under src/main/resources/template/KUTheme).  The checkboxlist.ftl theme that is part of the XHTML theme only includes a space between each label and the next checkbox (see checkboxlist.ftl in the template/simple 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.

In the example application there is a folder named src/main/webapp/template/KUTheme (for the Maven version, for the Ant version the path is WebContentresources/template/KUTheme). In that folder is a checkboxlist.ftl, the contents of which I originally copied from the checkboxlist.ftl that is in the templates.xhtml folder from the struts 2 core jar.

I then modified the checkboxlist.ftl in the KUTheme folder to be:

<#include "/${parameters.templateDir}/xhtml${parameters.expandTheme}/controlheader.ftl" />

<#include "/${parameters.templateDir}/KUTheme_simple/checkboxlist.ftl" />

<#include "/${parameters.templateDir}/xhtml${parameters.expandTheme}/controlfooter.ftl" /><#nt/>

Be sure to note the change to the first line—using xhtml in the path and the change to the second line—using KUTheme_simple in the path.

Then in the example application I created a KUTheme_simple folder under src/main/resources/template (optionally you can place it under webapp, e.g. src/main/webapp/template). In that folder I created checkboxlist.ftl and copied the contents from template.simple checkboxlist.ftl (again found in the Struts 2 core jar). After copying the contents to checkboxlist.ftl that is in KUTheme_simple folder, I modified checkboxlist.ftl 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.

In edit.jsp change the value of the theme attribute to be theme="KUTheme" for the Struts 2 checkboxlist tag. Since the XHTML theme is the default theme and I have a theme.properties file defined with parent = xhtml, the KUTheme will inherit all the themes from xhmtl exempt for the theme for the checkboxlist tag since my KUTheme includes a definition for that tag's layout.  In the struts.xml file (src/main/resources) you will see that the I've specified the default theme to be KUTheme.

In the deployed web application, Struts 2 will first look for a tag's template in web root/template/theme name and 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 checkboxlist.ftl file that is in the KUTheme_simple folder instead of the one in the template.simple folder that is part of the Struts 2 core Jar).

...