Page History

Info

title	About SiteMesh

...

SiteMesh is a web-page layout and decoration framework and web

...

application integration framework to aid in creating large sites consisting of many pages for which a consistent look/feel, navigation and layout scheme is required.

The Sitemesh plugin

Excerpt
allows Sitemesh templates to access framework resources

.

The framework Integrating WebWork with SiteMesh is amazingly simple: you don't have to do anything in fact. WebWork stores all its value stack information in the as request attributes, meaning that if you wish to display data that is in on the stack (or even the ActionContext), you can do so by using the normal tag libraries that come with WebWorkthe framework. That's it!

Passing data around

One thing to note is when you want to pass a value from a decorated page to a decorator using the <ww:set> tag, you need to specify a scope (request, session, application) if the decorated page is invoked directly (not a result of an action). By default if no action has been executed and no scope was specified, the set value will only availlable from the same PageContext. Look here for more information.

Velocity and FreeMarker Decorators

In WebWork's Architecture, the standard filter-chain optionally starts with the ActionContextCleanUp filter, followed by other desired filters. Lastly, the FilterDispatcher handles the request, usually passing it on to the ActionMapper. The primary purpose of the ActionContextCleanUp is for SiteMesh integration. This tells the FilterDispatcher when exactly, to clean-up the request. Otherwise, the ActionContext may be removed before the decorator attempts to access it.

Warning

title	Warning

If ActionContext access is required within the decorators, the ActionContextCleanUp filter must be placed at the beginning of the filter-chain.

Velocity

If you are using Velocity for your SiteMesh decorators, we recommend using the VelocityPageFilter. This is an extension of the SiteMesh PageFilter, which should be placed in the web.xml in between the ActionContextCleanUp and the FilterDispatcher. Now the Velocity decorators will have access to WebWork variables such as $stack and $request.

Wiki Markup

{snippet:id=example.velocity.filter.chain|javadoc=false|lang=xml|url=https://webwork.dev.java.net/source/browse/*checkout*/webwork/webapps/showcase/src/webapp/WEB-INF/web.xml?content-type=text%2Fplain}

FreeMarker

If you are using FreeMarker for your SiteMesh decorators, we recommend using the FreeMarkerPageFilter. This is an extension of the SiteMesh PageFilter, which should be placed in the web.xml in between the ActionContextCleanUp and the FilterDispatcher. Now the FreeMarker decorators will have access to WebWork variables such as ${stack} and ${request}.

...

Features

Can use Struts tags in Sitemesh decorator templates
Sitemesh decorators can be written in FreeMarker as well as Velocity and JSP

Usage

From 2.2+ the new com.opensymphony.sitemesh.webapp.SiteMeshFilter filter and Struts org.apache.struts2.dispatcher.ng.listener.StrutsListener context listener must be added to web.xml, like:

Code Block

	xml
	xml


<filter>
    <filter-name>sitemesh</filter-name>
    <filter-class>com.opensymphony.sitemesh.webapp.SiteMeshFilter</filter-class>
</filter> 
...
<listener>
    <listener-class>org.apache.struts2.dispatcher.ng.listener.StrutsListener</listener-class>
</listener>

FreeMarker and Velocity Decorators

The plugin provides an extension of the SiteMesh Velocity and FreeMarker servlets. These servlets provide the standard variables and Struts Tags that you used to create views in your favourite template language.

FreeMarker

From 2.2+ the recommended way to use Freemarker with Sitemesh is through the org.apache.struts2.sitemesh.FreemarkerDecoratorServlet servlet, which can be configured like this in web.xml:

Code Block

	xml
	xml


<servlet>
    <servlet-name>sitemesh-freemarker</servlet-name>
    <servlet-class>org.apache.struts2.sitemesh.FreemarkerDecoratorServlet</servlet-class>
    <init-param>
 	<param-name>default_encoding</param-name>
 	<param-value>UTF-8</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet> 

<servlet-mapping>
    <servlet-name>sitemesh-freemarker</servlet-name>
    <url-pattern>*.ftl</url-pattern>
</servlet-mapping>

Velocity

From 2.2+ the recommended way to use Velocity with Sitemesh is through the org.apache.struts2.sitemesh.VelocityDecoratorServlet servlet, which can be configured like this in web.xml:

Code Block

	xml
	xml


<servlet>
    <servlet-name>sitemesh-freemarker</servlet-name>
    <servlet-class>org.apache.struts2.sitemesh.VelocityDecoratorServlet</servlet-class>
    <init-param>
 	<param-name>default_encoding</param-name>
 	<param-value>UTF-8</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet> 

<servlet-mapping>
    <servlet-name>sitemesh-freemarker</servlet-name>
    <url-pattern>*.ftl</url-pattern>
</servlet-mapping>

Full integration with SiteMesh 2 + Freemarker 2.4.2 + Velocity 1.3 , including Struts 2 Tags, ValueStack, and FreemarkerManager statics.

Such configuration is available as from Struts 2.2.0, please refer to WW-3296 for me details.

Code Block

	xml
	xml


    <filter>
        <filter-name>struts-prepare</filter-name>
        <filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsPrepareFilter</filter-class>
    </filter>

    <filter>
        <filter-name>sitemesh</filter-name>
        <filter-class>com.opensymphony.sitemesh.webapp.SiteMeshFilter</filter-class>
    </filter>

    <filter>
        <filter-name>struts-execute</filter-name>
        <filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsExecuteFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>struts-prepare</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

    <filter-mapping>
        <filter-name>sitemesh</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>FORWARD</dispatcher>
        <dispatcher>INCLUDE</dispatcher>
    </filter-mapping>

    <filter-mapping>
        <filter-name>struts-execute</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

    <servlet>
        <servlet-name>sitemesh-freemarker</servlet-name>
        <servlet-class>org.apache.struts2.sitemesh.FreemarkerDecoratorServlet</servlet-class>
        <init-param>
            <param-name>default_encoding</param-name>
            <param-value>UTF-8</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>sitemesh-freemarker</servlet-name>
        <url-pattern>*.ftl</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>JspSupportServlet</servlet-name>
        <servlet-class>org.apache.struts2.views.JspSupportServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <listener>
        <listener-class>org.apache.struts2.dispatcher.ng.listener.StrutsListener</listener-class>
    </listener>

Example

Here is an example of how to configure the filter chains in web.xml:

Code Block

	xml
	xml


<filter>
    <filter-name>struts-prepare</filter-name>
    <filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsPrepareFilter</filter-class>
</filter>

<filter>
    <filter-name>struts-execute</filter-name>
    <filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsExecuteFilter</filter-class>
</filter>


<filter>
    <filter-name>sitemesh</filter-name>
    <filter-class>com.opensymphony.sitemesh.webapp.SiteMeshFilter</filter-class>
</filter>

<filter-mapping>
    <filter-name>struts-prepare</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
    <filter-name>sitemesh</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
    <filter-name>struts-execute</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

<listener>
    <listener-class>org.apache.struts2.dispatcher.ng.listener.StrutsListener</listener-class>
</listener>

<servlet>
    <servlet-name>sitemesh-freemarker</servlet-name>
    <servlet-class>org.apache.struts2.sitemesh.FreemarkerDecoratorServlet</servlet-class>
    <init-param>
        <param-name>default_encoding</param-name>
        <param-value>UTF-8</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

<servlet>
    <servlet-name>sitemesh-velocity</servlet-name>
    <servlet-class>org.apache.struts2.sitemesh.VelocityDecoratorServlet</servlet-class>
    <init-param>
        <param-name>default_encoding</param-name>
        <param-value>UTF-8</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
    <servlet-name>sitemesh-freemarker</servlet-name>
    <url-pattern>*.ftl</url-pattern>
</servlet-mapping>

<servlet-mapping>
    <servlet-name>sitemesh-velocity</servlet-name>
    <url-pattern>*.vm</url-pattern>
</servlet-mapping>

Struts 2.1 web.xml filter chain example:

Code Block

	xml
	xml


<filter>
    <filter-name>struts-prepare</filter-name>
    <filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsPrepareFilter</filter-class>
</filter>

<filter>
    <filter-name>struts-execute</filter-name>
    <filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsExecuteFilter</filter-class>
</filter>

<filter>
    <filter-name>sitemesh</filter-name>
    <filter-class>com.opensymphony.module.sitemesh.filter.PageFilter</filter-class>
</filter>

<filter-mapping>
    <filter-name>struts-prepare</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
    <filter-name>sitemesh</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
    <filter-name>struts-execute</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

You do not need the struts2-sitmesh-plugin if you are using JSP for your decorators.
Here are the only only changes needed to web.xml

Code Block

	xml
	xml


<filter>
    <filter-name>struts2-prepare</filter-name>
    <filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsPrepareFilter</filter-class>
</filter>

<filter>
    <filter-name>sitemesh</filter-name>
    <filter-class>com.opensymphony.sitemesh.webapp.SiteMeshFilter</filter-class>
</filter>

<filter>
    <filter-name>struts2-execute</filter-name>
    <filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsExecuteFilter</filter-class>
</filter>

<filter-mapping>
    <filter-name>struts2-prepare</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
    <filter-name>sitemesh</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>INCLUDE</dispatcher>
</filter-mapping>

<filter-mapping>
    <filter-name>struts2-execute</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Settings

This plugin doesn't support any global settings.

Installation

This plugin can be installed by copying the plugin jar into your application's /WEB-INF/lib directory. No other files need to be copied or created.

...

Child pages

Versions Compared

Old Version 27

New Version Current

Key

Passing data around

Velocity and FreeMarker Decorators

Velocity

FreeMarker

Features

Usage

FreeMarker and Velocity Decorators

FreeMarker

Velocity

Full integration with SiteMesh 2 + Freemarker 2.4.2 + Velocity 1.3 , including Struts 2 Tags, ValueStack, and FreemarkerManager statics.

Example

Settings

Installation