java - Can someone explain how to use FastTags

Question

There are two ways to create customs tags with the play framework.

1. By defining a groovy template in app/view/tags
2. Directly in pure java by having a class extend FastTags

The latest is NOT documented.

Answer 1

So, similar to how JavaExtensions work by extending the JavaExtensions class, to create a FastTag you need to create a class that extends FastTags. Each method that you want to execute as a tag needs to conform to the following method structure.

public static void _tagName(Map<?, ?> args, Closure body, PrintWriter out, ExecutableTemplate template, int fromLine)

Note the underscore before the name of the tag.

To understand how to build an actual tag, the easiest way is to look at the source code for a FastTag, and see one in action.

Here is the source straight from git hub. https://github.com/playframework/play/blob/master/framework/src/play/templates/FastTags.java

Below are a few I have copied, so that I can explain how this works.

public static void _verbatim(Map<?, ?> args, Closure body, PrintWriter out, ExecutableTemplate template, int fromLine) {
    out.println(JavaExtensions.toString(body));
}

So, this first method is the verbatim tag, and simply calls the toString method on the JavaExtensions, and passes in the body of the tag. The body of the tag would be anything between the open and close tag. So

<verbatim>My verbatim</verbatim>

The body value would be

My verbatim

The second example, is slightly more complex. It is a tag that relies on a parent tag to function.

public static void _option(Map<?, ?> args, Closure body, PrintWriter out, ExecutableTemplate template, int fromLine) {
    Object value = args.get("arg");
    Object selectedValue = TagContext.parent("select").data.get("selected");
    boolean selected = selectedValue != null && value != null && selectedValue.equals(value);
    out.print("<option value="" + (value == null ? "" : value) + "" " + (selected ? "selected="selected"" : "") + "" + serialize(args, "selected", "value") + ">");
    out.println(JavaExtensions.toString(body));
    out.print("</option>");
}

This code works by outputting an HTML option tag, and sets the selected value, by checking which value is selected from the parent tag. The first 3 lines just get data, and set up the data ready to output. Then, the final 3 lines outputs the result of the tag.

There are many more examples in the source code I have linked to, with varying degrees of complexity, but hopefully this will be a good starting point for you.

To ensure that your tags do not conflict between projects, or with the core Play tags, you can set up namespaces, using the class level annotation @FastTags.Namespace.

So, for a hello tag, in a namespace of my.tags, you would do the following

@FastTags.Namespace("my.tags") 
public class MyFastTag extends FastTags {
    public static void _hello (Map<?, ?> args, Closure body, PrintWriter out, ExecutableTemplate template, int fromLine) {
        ...
    }
}

and then in your templates, you would reference the hello tag as

#{my.tags.hello/}