Page History

FreeMarker tags are extensions of the generic Struts Tags and UI Components provided by WebWorkthe framework. You can get started almost immediately by simply jump right in just by knowing the generic structure in which the tags can be accessed: <@ww<@s.xxx> tag> ...</@ww@s.xxx>tag>, where xxx tag is any of the tags supported by WebWorkthe framework.

...

For example, in JSP you might create a form like so:using Struts tags.

<ww<s:form action="updatePerson">
    <ww<s:textfield label="First name" name="firstName"/>
    <ww<s:submit value="Update"/>
</wws:form>

In FreeMarker the same form is built like so:can also be built using Struts tags.

<@ww<@s.form action="updatePerson">
    <@ww<@s.textfield label="First name" name="firstName"/>
    <@ww<@s.submit value="Update"/>    
</@ww@s.form>

But, wait there's more!

Aside from doing everything that the JSP tags do, the FTL tags boast additional features that you can use to make your pages even easier to code. You can even invoke third-party JSP taglibs as if there were native FTL tagsWhile this covers almost all know need to know for for FreeMarker tags, there are a few other advanced features you should read about, specifically with how attributes and parameters work together, and how attribute types (String, List, etc) can affect the tag behavior.

Attributes and Parameters

Unlike older versions of JSP (in which the JSP Tags are based), FreeMarker allows for dynamic attributes, much like JSP 2.0. What this means is that you You can supply attributes to the tags that the tag doesn't even explicitedly support. Those attributes that cannot be applied directly to the tag object will instead be set on to the tag's general-purpose parameters map. Map.

Suppose we wanted to build an URL in a JSP. The URL needs to take an arbitary parameter to the query string, that (being arbitary) isn't specified on the URL tag. In a JSP, we'd have to use the url and param tags together.For example, suppose you have the following code in JSP:

<ww<s:url value="somePage">
    <ww<s:param name="personId" value="%{personId}"/>
</wws:url>

In FreeMarker, you can simplify this as:we can pass the arbitrary parameter directly and create the URL in one simple statement.

<@s
<@ww.url value="somePage" personId="${personId}"/>

Using inline attributes with templates

Suppose In addition to being able to replace cases where you might use the param tag, you can also use this functionality when building additional templates or themes for your Form Tags. For example, suppose you created a "three column" theme to replace the typical two column theme (xhtml). You might want an additional parameter to display in the third column called "description". Your form can be:Using FreeMarker, you can just pop the description attribute into the textfield tag, no fuss, no muss.

<@s
<@ww.form action="updatePerson">
    <@ww<@s.textfield label="First name" name="firstName" description="..."/>
    <@ww<@s.submit value="Update"/>    
</@ww@s.form>

And then in your In the new template you can refer to , the description using is referenced via the parameters Map: "${parameters.description}".

Attribute Types

Remember that all tag attributes must first be set as Strings – - they are then later evaluated (using OGNL) to a different type, such as List, int, or boolean. This generally works just fine, but it can be limiting when using FreeMarker which provides more advanced ways to apply attributes. Suppose the following example:

<@ww<@s.select label="Foo label - ${foo}" name="${name}" list="%{{1, 2, 3}}"/>

What will happen here is that each attribute will be evaluated to a string String as best it can. This may involve calling the toString() method on the internal FreeMarker objects in the hash. In this case, all objects will end up being exactly what you would expect. Then, when the tag runs, the list attribute will be converted from a String to a List using OGNL's advanced collection support.

But suppose you wish to use FreeMarker's list or hash support instead? You can do this:

<@ww<@s.select label="Foo label - ${foo}" name="${name}" list={[1, 2, 3}]/>

Wiki MarkupNotice that the list attribute no longer has quotes around it. Now it will come in to the tag as an object that can't easily be converted to a String. Normally, the tag would just call toString(), which would return "\[1, 2, 3\]" and be unable to be converted back to a List by OGNL. Rather than go through all this back and forth anyway, the frameworks's FreeMarker tag support within WebWork will recognize collections and not pass them through the normal tag attribute, but instead set them directly in the *parameters* map, ready to be consumed by the . Instead, the framework will set them directly in the parameters Map, ready to be consumed by the template.

In the end, everything tends to do what you would expect, but it can help to understand the difference of when OGNL is being used and when it isn't, and how attribute types get converted.

JSP Tag Support

While the framework provides native FreeMarker Tags, you might wish to use other third-party tags that are only available for JSP. Fortunately, FreeMarker has the ability to run JSP tags. To do so, you must include the JspSupportServlet in the application's web.xml, as this allows the FreeMarker integration to get access to the required objects needed to emulate a JSP taglib container.

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

Once you've done that, you can simply add something like this in your templates:

<#assign cewolf=JspTaglibs["/WEB-INF/cewolf.tld"] />
...
<@cewold.xxx ... />

Next: Velocity