THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
| Info | ||
|---|---|---|
|
...
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.
Localization
WebWork provides easy to use i18n functionality to SiteMesh decorators. Now using the <ww:text/> tag works seemlessly. In the event where you need to reference an i18n string, use the id attribute as documented in the Text tag. An example of such situation is given below.
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 | ||||
|---|---|---|---|---|
| ||||
<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.xmlTypically embedding i18n in to form elements would be done using the following:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<ww:textfield label="%{getText('com.acme.login.text')}" name="login"/> <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:However, due to the way WebWork and SiteMesh work, you would need to seperate the above code in to two tags.
| Code Block | ||||
|---|---|---|---|---|
| ||||
<ww:text id="login" name="com.acme.login.text"/>
<ww:textfield label="#login" name="login"/>
|
Velocity and FreeMarker Decorators
In WebWork's Architecture, the standard chain of filters optionally starts with the ActionContextCleanUp filter, followed by the users other desired filters. Then, the FilterDispatcher handles the request, passing it on to the ActionMapper.
WebWork provides extensions to the
<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 | ||||
|---|---|---|---|---|
| ||||
<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 | ||||
|---|---|---|---|---|
| ||||
<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 | ||||
|---|---|---|---|---|
| ||||
<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 | ||||
|---|---|---|---|---|
| ||||
<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 createdIf you are using Velocity for your SiteMesh decorators, we recommend not using the WebWorkVelocityServlet or the SiteMeshVelocityServlet. In fact, we don't recommend you use any servlet at all. Instead, try creating a servlet that extends PageFilter and then using that servlet in place of PageFilter in web.xml. In your cusotm servlet, override the applyDecorator() method and then use WebWork's VelocityManager to access your decorator templates. You can use VelocityManager to create a default Context as well, which will include all the WebWork variables such as $stack. Then simply add the Page object to the context and then you can access the page parts using $page.title, $page.body, etc.