Fork me on GitHub

Creating a generic tag library

A generic tag library is a jar file including the classes that implement the tags and a library descriptor META-INF/template-suite.xml, that can be used by Autotag to build specific tag libraries for Freemarker, JSP, and Velocity.

The structure of the library descriptor is rather complex; fortunately Autotag can generate it for you by parsing the sources.

The tag class

A tag in the library can be implemented by any java class that fits the following requirements:

  • The class name ends with Model.
  • It has a public, non-static, non-abstract method called execute.
  • The execute method returns void.
  • The parameters of the execute method are as follows:
  • the first parameters may be anything you want; at runtime they will contain the values assigned to the attributes of the tag in the template. Those parameters may be annotated with org.apache.tiles.autotag.core.runtime.annotation.Parameter in order to specify the name of the attribute, the default value, or to make the parameter mandatory.
  • then, one parameter of type org.apache.tiles.request.Request.
  • and finally, one optional parameter of type org.apache.tiles.autotag.core.runtime.ModelBody; at runtime it will contain the contents of the tag in the template.

    For instance:

    public class MyTagModel {
    
        public void execute( 
            @Parameter(required=true) String mandatoryParam, 
            String optionalParam, 
            Request request, 
            ModelBody body) {
            ...
        }
    
    }

Generating the library descriptor

the library descriptor can be generated using the create-descriptor goal of maven-autotag-plugin.

<plugin>
  <groupId>org.apache.tiles.autotag.plugin</groupId>
  <artifactId>maven-autotag-plugin</artifactId>
  <version>1.0</version>
  <executions>
    <execution>
      <goals>
        <goal>create-descriptor</goal>
      </goals>
      <configuration>
        ...
      </configuration> 
    </execution>
  </executions>
</plugin>

Configuration reference

name
is the name of the tag library (for instance: tiles). It will be used for naming a number of generated files.
documentation
is a documentation that will be included in the library descriptor, and then later in the appropriate artefacts when generating the taglibs.
includes
specifies what source files should be included, defaults to **/*Model.java. It follows the usual conventions in maven.
excludes
specifies what source files should be included, defaults to nothing. It follows the usual conventions in maven.
outputDirectory
specifies where to put the generated files, defaults to target/autotag-template-suite.