FastTags in Play

Recently in the Play user groups, and on StackOverflow, there have been a number of questions regarding FastTags in Play. Having answered the question on StackOverflow, I thought I would add a post here, to show Fast Tags in action, because they are

1. Very Simple to implement
2. Very powerful tools

So what are FastTags

So let’s start with the basics. What exactly are FastTags?

If you read the online documentation, you will already have been introduced to the concept of creating your own tags. These tags are effectively Groovy/HTML code snippets that can pass named parameters  into the snippet to perform a re-usable piece of code. An example of a Groovy Tag (straight from the online docs):

To create a hello world tag, the tag code would be created in the app/views/tags directory, and named <tagname>.html. So a hello tag would be called hello.html. The tag code would look like this:

Hello ${_name} !

And we would use the tag in our views, like this:

#{hello name:'Bob' /}

Which when we run our view, we would see the output:

Hello Bob !

A very simply Hello World example. However, there is another way to create this tag, and that is where Fast Tags come in.

But Why Bother? What’s wrong with Groovy Tags?

Okay, so good question. And the answer is, it depends on the scenario. Groovy tags are great for taking repetitive or re-usable code out of a view, and making it a re-usable component. It allows great re-use at the view layer. But it is limited to HTML/Groovy code or the use of the script tag. Just like JavaExtensions give you the ability to take complex logic and abstract it out of the presentation layer, the FastTags give you the same power.

All of the tags that you are already using within Play are written using FastTags (see the source on github), so there is already a good set of examples for you to work with.

Well Show Me Then!
Okay, let’s once again see what we need to do to get a Hello World tag working.

A fast tag library needs to extend FastTags, and can have  a number of different tags contained in each class. The class can exist anywhere in the package structure, but I would suggest storing it app/tags as a neat place to keep them.

So, lets assume our tag library will be called MyFastTags

package tags;

import groovy.lang.Closure;
import play.templates.*;
import play.templates.GroovyTemplate.ExecutableTemplate;
import java.util.*;
import java.io.PrintWriter;

@FastTags.Namespace("mytags")
public class MyFastTag extends play.templates.FastTags {
   public static void _hello (Map<?, ?> args, Closure body, PrintWriter out, ExecutableTemplate template, int fromLine) {
      out.println("Hello " + args.get("name").toString() + " !");
   }
}

So, there are a few things that are happening in this code. First of all we have set the package structure according to the directory we saved out tag to (app/tags).
We then import a list of packages needed for the FastTag to work.
Next, we have specified a namespace for the tag. This helps prevent conflicts, between different tag packages.
We then specify the class name, and extend FastTags (which is a must for the Play framework to pick this up as a tag).
The next 3 lines of code is the content of our tag. The method name _hello tells Play that our tag is name hello. The underscore is a required Play style that must be followed for your tag to work.
Our tag itself is very basic in this example. We are simply getting the variable name that is passed in, and output a String with the name inside the String.

To use our tag in the code, because we have used a namespace, we access the tag in a slightly different way. We use

#{mytags.hello name:'Bob' /}

The output is then identical to the hello world tag that we used previously.

You can imagine though that this approach could result in very powerful, re-usable tags that could significantly reduce presentation coding and rework. A good example that was released a few days ago was the JQValidate module. The module is a single FastTag with a few tags contained within it that allowed, form validation to be carried out client side, using the server side annotations of the Model. Doing this kind of tag in Groovy (without a lot of scripting, which is bad practice) would be impossible.

Try it out for yourself, and see what you can do! Whilst I don’t believe FastTags are the answer to all your tagging needs, because Groovy tags are perfect for purely presentation layer type tasks, FastTags open up another area of flexible development and will no-doubt make your development easier, especially as you (and the community) build up libraries of re-usable FastTags.