Download It – Struts2-Theme-Example.zip

In Struts2, when you put a “s:textfield” UI tag in the HTML page

<s:textfield key="global.username" name="username" />

The following 2 columns HTML table layout design will be generated automatically

<tr>
<td class="tdLabel">
  <label for="validateUser_username" class="label">Username:</label>
</td>
<td>
  <input type="text" name="username" value="" id="validateUser_username"/>
</td>
</tr>

Struts 2 is using the “Theme & template” feature to generate the pre-designed table layout for you.

Let’s see the sequences :

  1. Struts 2 see a “s:textfield” tag.
  2. Search the declared theme (if no theme declared , the default xhtml theme will be select).
  3. Search the corresponds theme’s template, e.g “s:textfield -> text.ftl” , “s:password ->password.ftl“. All the pre-defined HTML layout is defined in the ftl file.
  4. Bind the value into the template file.
  5. Display the final HTML markup.
Struts 2 tags + Theme’s template file (ftl) = Final HTML markup code.
Struts 2 is using the freemaker framework as the default template engine, all ftl files are written in freemaker script. No worry, the freemarker syntax is almost in human explains words, it’s quite easy to learn.

Working with Struts 2 Theme & Template

In this article, you will create a new theme to customize the error message location. In the default “xhtml” theme, the error message will appear above the field name.

Struts2 xhtml theme

In new theme, the error message will display beside the input field and highlight with a red color.

Struts2 mkyong theme

1. Extract the Theme

All the theme and template files are inside the struts2-core.jar, template folder. Extract it to your local drive.

The ftl file is just a normal text file, you can open it with any prefer text editors.

2. Create a new Theme

Create a new folder, copy all the existing xhtml template files (ftl) and put the new folder into project resource folder.

Struts 2 theme folder
To understand how Struts 2 find the theme template folder, read Struts 2 template directory selection for more detail.
Often times, you just need to copy and modify the existing “xhtml” theme, unless you have reason not to.

3. Define a new Theme

Define the “struts.ui.theme” and “struts.ui.templateDir” to tell Struts 2 where to find your new theme and template folder.

struts.xml

<struts>
    ...
 	<constant name="struts.ui.theme" value="mkyong" />
	<constant name="struts.ui.templateDir" value="template" />
	...
</struts>
Now, when Struts 2 see a “s:textfield“, it will find the “mkyong” theme instead of the default “xhtml” theme. Read Struts 2 select a theme for more detail.

4. Modify the Theme

To modify the existing template (ftl) file, you may need to know a bit freemarker syntax.

1. Create a new error-message.ftl file to display the error message.

error-message.ftl

<#--
	Only show message if errors are available.
	This will be done if ActionSupport is used.
-->
<#assign hasFieldErrors = parameters.name?? && fieldErrors?? && fieldErrors[parameters.name]??/>
<#if hasFieldErrors>
<#list fieldErrors[parameters.name] as error>
   <span class="errorMessage" errorFor="${parameters.id}">${error?html}</span><#t/>
</#list>
</#if>

2. Modify the controlheader.ftl by adding a new “errorsBg” class to “td” tag if errors exists.

controlheader.ftl

<#include "/${parameters.templateDir}/mkyong/controlheader-core.ftl" />
    <td
<#if hasFieldErrors>
    class="errorsBg" <#t/>
</#if>
<#if parameters.align??>
    align="${parameters.align?html}"<#t/>
</#if>
><#t/>

3. Modify the controlheader-core.ftl by delete many unnecessary tags and add a new “errorsBg” class to “td” tag if errors exists.

controlheader-core.ftl

<#--
	Only show message if errors are available.
	This will be done if ActionSupport is used.
-->
<#assign hasFieldErrors = parameters.name?? && fieldErrors?? && fieldErrors[parameters.name]??/>
<#--
	if the label position is top,
	then give the label its own row in the table
-->
<tr>
 
<td class="tdLabel <#t/>
<#--
<#if hasFieldErrors>
errorsBg"<#t/>
</#if>
-->
><#rt/>
 
<#if parameters.label??>
    <label <#t/>
<#if parameters.id??>
        for="${parameters.id?html}" <#t/>
</#if>
<#if hasFieldErrors>
        class="errorLabel"<#t/>
<#else>
        class="label"<#t/>
</#if>
 ><#t/>
 
<#if parameters.required?default(false) && parameters.requiredposition?default("right") != 'right'>
    <span class="required">*</span><#t/>
</#if>
${parameters.label?html}<#t/>
<#if parameters.required?default(false) && parameters.requiredposition?default("right") == 'right'>
 	<span class="required">*</span><#t/>
</#if>
 
</label><#t/>
</#if>
 
</td><#lt/>

4. Modify the text.ftl by adding a new template file “error-message.ftl” after the “simple/text.ftl“.

text.ftl

<#include "/${parameters.templateDir}/${parameters.theme}/controlheader.ftl" />
<#include "/${parameters.templateDir}/simple/text.ftl" />
<#include "/${parameters.templateDir}/mkyong/error-message.ftl" />
<#include "/${parameters.templateDir}/xhtml/controlfooter.ftl" />

5. Put the CSS in your view page to format the error message.

<style type="text/css">
.errorsBg{
	background-color:#fdd;
	color:red;	
	border: 1px solid;
}
 
.errorMessage{
	padding:0px 8px;
}
 
table{
	border-spacing: 4px;
}
td{
	padding:4px;
}
</style>

5. Done, saved it, now the error message will display beside the input field and highlight with red color.

Hope this article can give you a general concept about how to create or modify a theme in Struts2.

Reference

  1. http://freemarker.sourceforge.net/
  2. http://www.vitarara.org/cms/struts_2_cookbook/creating_a_theme
  3. http://struts.apache.org/2.0.14/docs/themes-and-templates.html
  4. http://www.packtpub.com/article/themes-and-templates-with-apache-struts2
Tags :
Founder of Mkyong.com and HostingCompass.com, love Java and open source stuff. Follow him on Twitter, or befriend him on Facebook or Google Plus. If you like my tutorials, consider making a donation to this charity, thanks.

Related Posts

Popular Posts