Methods

Method variables exposed to a template implement the TemplateMethodModel interface. This contains one method: TemplateModel exec(java.util.List arguments). When you call a method with a method call expression, then the exec method will be called. The arguments parameter will contain the values of the FTL method call arguments. The return value of exec gives the value of the FTL method call expression.

The TemplateMethodModelEx interface extends TemplateMethodModel. It does not add any new methods. The fact that the object implements this marker interface indicates to the FTL engine that the arguments should be put to the java.util.List directly as TemplateModel-s. Otherwise they will be put to the list as String-s.

For obvious reasons there is no default implementation for these interfaces.

Example: This is a method, which returns the index within the second string of the first occurrence of the first string, or -1 if the second string doesn't contains the first.

public class IndexOfMethod implements TemplateMethodModel {
    
    public TemplateModel exec(List args) throws TemplateModelException {
        if (args.size() != 2) {
            throw new TemplateModelException("Wrong arguments");
        }
        return new SimpleNumber(
            ((String) args.get(1)).indexOf((String) args.get(0)));
    }
}

If you put an instance of this, say, into the root:

root.put("indexOf", new IndexOfMethod());

then you can call it in the template:

[#set x = "something"]
${indexOf("met", x)}
${indexOf("foo", x)}

and then the output will be:

2
-1

If you need to access the runtime FTL environment (read/write variables, get the current locale, etc.), you can get it with Environment.getCurrentEnvironment().

Methods with lazily evaluated arguments

A method class can also implement the LazilyEvaluatableArguments marker interface. This interface has no methods and can be implemented by either TemplateMethodModel or TemplateMethodModelEx implementors. A method class implementing it declares that it wants its argument expressions to be lazily evaluated. This means that each expression will only be evaluated when first requested from the list during the method call. The arguments not used in the method call will not be evaluated at all. In contrast, "normal" methods (those not implementing the LazilyEvaluatableArguments interface) are called with all of their argument expressions pre-evaluated before the call, in a strict left-to-right order.

Warning!

As this behavior is unusual, it should be used in the most justified cases only (not for mere performance optimization). The typical justification is that you want some arguments not to be evaluated at all for semantic reasons. For example lazily evaluated arguments are used by the string built-in for booleans because it's very much like expr ? expr : expr in the Java Language.

Note that any TemplateException-s that occur during lazy argument evaluation will be wrapped into an instance of runtime exception freemarker.template.utility.UndeclaredThrowableException as TemplateException can not be thrown from java.util.List methods.


FreeMarker Manual -- For FreeMarker 2.4pre1 - INCOMPLETE/OUTDATED! HTML generated: 2009-03-29 13:52:16 GMT