Scooter Framework

Using your own template file types

Scooter comes with supports for JSP (.jsp files) and StringTemplates (.st files). What if you like to use your own template file types, such as Velocity or FreeMarker or Dryml? It is fairly easy. Just do the following:

1. Call the view in Controller class by using renderView methods
2. Write a template handler plugin
3. Register the plugin in environment.properties
4. Put your plugin class in a jar file in the plugins directory

Call the view in Controller class by using renderView methods

If some of your views are of the type, for example, dryml, you can name the view files with .dryml extension, and call one of the overloaded renderView methods:

public class PostsController {
    /**
     * show method returns a post record.
     * Example request url: GET /posts/101
     */
    public String show() {
        ActiveRecord post = Post.findById(p("id"));
        if (post == null) {
            flash("notice", "There is no post record with primary key id as " + p("id") + ".");
        }
        else {
            setViewData("post", post);
        }
        return renderView("show.dryml");//return result in html format
        //return renderView("show.dryml", "text");//return result in text format
    }
}

Here show.dryml is a template file based on dryml syntax for displaying details of a post record. The renderView method returns processed content in html by default.

If all of your views have dryml extension, then you can set view.extension=dryml in WEB-INF/config/environment.properties property file and omit the view template file extension in the above code:

public class PostsController {
    public String show() {
        ....
        return renderView("show");//return result in html
    }
}

Write a template handler plugin

To let Scooter knows that you need to handle content in .dryml files, you simply write a template handler plugin class. A template handler knows how to map data properties with tokens in the template file.

The following is an example implementation of DrymlTemplateHandler:

package com.example.template;

import com.scooterframework.admin.Plugin;
import com.scooterframework.web.controller.TemplateHandler;

public class DrymlTemplateHandler extends Plugin implements TemplateHandler {
    /**
     * Handles processing the content with props.
     *
     * @param content  The content to be processed.
     * @param props  properties (name/value pairs) to be used to process the content
     * @return processed content as string
     */
    public String handle(String content, Map props) {
    	...;
    }

    /**
     * Handles processing the viewTemplate with props.
     *
     * @param viewTemplate The template file
     * @param props  properties (name/value pairs) to be used to process the content
     * @return processed content as string
     */
    public String handle(File viewTemplate, Map props) {
    	String content = getTemplateFileContent(viewTemplate);
    	return handle(content, props);
    }
}

You can see an implementation of handle methods in com.scooterframework.web.controller.StringTemplateHandler.

Register the plugin in environment.properties

Registering a template handler plugin in the environment.properties property file:

# Configure a dryml template handler plugin to handle templates with .dryml extension:
plugin.template.handler.dryml=\
                plugin_class=com.example.template.DrymlTemplateHandler

You can add other properties too if your handler class requires some special properties:

# Configure a dryml template handler plugin to handle templates with .dryml extension:
plugin.template.handler.dryml=\
                plugin_class=com.example.template.DrymlTemplateHandler,\
                other_property_name=other_value,\
                more_property_name=more_value

When you register the plugin, please follow the naming convention of the template handler plugin:

plugin.template.handler.{template extension}=...

Put your plugin class in a jar file in the plugins directory

All jar files in the plugins directory are loaded by the framework at startup time. Other required 3rd-party jar files should also be there in the same subdirectory.