Directives

Java programmers can implement user-defined directives in Java using the TemplateDirectiveModel interface. See in the API documentation.

Note

TemplateDirectiveModel was introduced in FreeMarker 2.3.11, replacing the soon to be depreciated TemplateTransformModel.

Example 1

We will implement a directive which converts all output between its start-tag and end-tag to upper case. Like, this template:

foo
<@upper>
  bar
  <#-- All kind of FTL is allowed here -->
  <#list ["red", "green", "blue"] as color>
    ${color}
  
  baaz

wombat

will output this:

foo
  BAR
    RED
    GREEN
    BLUE
  BAAZ
wombat

This is the source code of the directive class:

package com.example;
import java.io.IOException;
import java.io.Writer;
import java.util.Map;

import freemarker.core.Environment;
import freemarker.template.TemplateDirectiveBody;
import freemarker.template.TemplateDirectiveModel;
import freemarker.template.TemplateException;
import freemarker.template.TemplateModel;
import freemarker.template.TemplateModelException;

/**
 *  FreeMarker user-defined directive that progressively transforms
 *  the output of its nested content to upper-case.
 *  
 *  
 *  Directive info

 * 
 *  Directive parameters: None
 *  
Loop variables: None
 *  
Directive nested content: Yes
 */
public class UpperDirective implements TemplateDirectiveModel {

    public void execute(Environment env,
            Map params, TemplateModel[] loopVars,
            TemplateDirectiveBody body)
            throws TemplateException, IOException {
        // Check if no parameters were given:
        if (!params.isEmpty()) {
            throw new TemplateModelException(
                    "This directive doesn't allow parameters.");
        }
        if (loopVars.length != 0) {
                throw new TemplateModelException(
                    "This directive doesn't allow loop variables.");
        }

        // If there is non-empty nested content:
        if (body != null) {
            // Executes the nested body. Same as <#nested> in FTL, except
            // that we use our own writer instead of the current output writer.
            body.render(new UpperCaseFilterWriter(env.getOut()));
        } else {
            throw new RuntimeException("missing body");
        }
    }

    /**
     * A {@link Writer} that transforms the character stream to upper case
     * and forwards it to another {@link Writer}.
     */ 
    private static class UpperCaseFilterWriter extends Writer {

        private final Writer out;

        UpperCaseFilterWriter (Writer out) {
            this.out = out;
        }

        public void write(char[] cbuf, int off, int len)
                throws IOException {
            char[] transformedCbuf = new char[len];
            for (int i = 0; i < len; i++) {
                transformedCbuf[i] = Character.toUpperCase(cbuf[i + off]);
            }
            out.write(transformedCbuf);
        }

        public void flush() throws IOException {
            out.flush();
        }

        public void close() throws IOException {
            out.close();
        }
    }

}

Now we still need to create an instance of this class, and make this directive available to the template with the name "upper" (or with whatever name we want) somehow. A possible solution is to put the directive in the data-model:

root.put("upper", new com.example.UpperDirective());

But typically it is better practice to put commonly used directives into the Configuration as shared variables.

It is also possible to put the directive into an FTL library (collection of macros and like in a template, that you include or import in other templates) using the new built-in:

<#-- Maybe you have directives that you have implemented in FTL -->
<#macro something>
  ...


<#-- Now you can't use <#macro upper>, but instead you can: -->
<#assign upper = "com.example.UpperDirective"?new()>

Example 2

我们��创��Z��个指令的执行指定的次敎ͼ�同样列出指��o�Q�随意分隔与一�?lt;hr> - S的repetations输出�Q�其嵌套的内容，再学习�?/span> 让我们把�q�种指��o“重复”�?/span> 例如模板�Q?/span>

<#assign x = 1>

<@repeat count=4>
  Test ${x}
  <#assign x = x + 1>


<@repeat count=3 hr=true>
  Test


<@repeat count=3; cnt>
  ${cnt}. Test

Output:

  Test 1
  Test 2
  Test 3
  Test 4

  Test
  Test
  Test

  1. Test
  2. Test
  3. Test

The class:

package com.example;
import java.io.IOException;
import java.io.Writer;
import java.util.Iterator;
import java.util.Map;

import freemarker.core.Environment;
import freemarker.template.SimpleNumber;
import freemarker.template.TemplateBooleanModel;
import freemarker.template.TemplateDirectiveBody;
import freemarker.template.TemplateDirectiveModel;
import freemarker.template.TemplateException;
import freemarker.template.TemplateModel;
import freemarker.template.TemplateModelException;
import freemarker.template.TemplateNumberModel;

/**
 * FreeMarker user-defined directive for repeating a section of a template,
 * optionally with separating the output of the repetations with
 * <hr>-s.
 *
 * 
 * Directive info

 * 
 * Parameters:
 * 

 *   count: The number of repetations. Required!
 *       Must be a non-negative number. If it is not a whole number then it will
 *       be rounded down.
 *   
hr: Tells if a HTML "hr" element could be printed between
 *       repetations. Boolean. Optional, defaults to false. 
 * 

 *
 * Loop variables: One, optional. It gives the number of the current
 *    repetation, starting from 1.
 * 
 * 
Nested content: Yes
 */
public class RepeatDirective implements TemplateDirectiveModel {

    private static final String PARAM_NAME_COUNT = "count";
    private static final String PARAM_NAME_HR = "hr";

    public void execute(Environment env,
            Map params, TemplateModel[] loopVars,
            TemplateDirectiveBody body)
            throws TemplateException, IOException {

        // ---------------------------------------------------------------------
        // Processing the parameters:

        int countParam = 0;
        boolean countParamSet = false;
        boolean hrParam = false;

        Iterator paramIter = params.entrySet().iterator();
        while (paramIter.hasNext()) {
            Map.Entry ent = (Map.Entry) paramIter.next();

            String paramName = (String) ent.getKey();
            TemplateModel paramValue = (TemplateModel) ent.getValue();

            if (paramName.equals(PARAM_NAME_COUNT)) {
                if (!(paramValue instanceof TemplateNumberModel)) {
                    throw new TemplateModelException(
                            "The \"" + PARAM_NAME_HR + "\" parameter "
                            + "must be a number.");
                }
                countParam = ((TemplateNumberModel) paramValue)
                        .getAsNumber().intValue();
                countParamSet = true;
                if (countParam < 0) {
                    throw new TemplateModelException(
                            "The \"" + PARAM_NAME_HR + "\" parameter "
                            + "can't be negative.");
                }
            } else if (paramName.equals(PARAM_NAME_HR)) {
                if (!(paramValue instanceof TemplateBooleanModel)) {
                    throw new TemplateModelException(
                            "The \"" + PARAM_NAME_HR + "\" parameter "
                            + "must be a boolean.");
                }
                hrParam = ((TemplateBooleanModel) paramValue)
                        .getAsBoolean();
            } else {
                throw new TemplateModelException(
                        "Unsupported parameter: " + paramName);
            }
        }
        if (!countParamSet) {
                throw new TemplateModelException(
                        "The required \"" + PARAM_NAME_COUNT + "\" paramter"
                        + "is missing.");
        }

        if (loopVars.length > 1) {
                throw new TemplateModelException(
                        "At most one loop variable is allowed.");
        }

        // Yeah, it was long and boring...

        // ---------------------------------------------------------------------
        // Do the actual directive execution:

        Writer out = env.getOut();
        if (body != null) {
            for (int i = 0; i < countParam; i++) {
                // Prints a 
 between all repetations if the "hr" parameter
                // was true:
                if (hrParam && i != 0) {
                    out.write("
");
                }

                // Set the loop variable, if there is one:
                if (loopVars.length > 0) {
                    loopVars[0] = new SimpleNumber(i + 1);
                }

                // Executes the nested body (same as <#nested> in FTL). In this
                // case we don't provide a special writer as the parameter:
                body.render(env.getOut());
            }
        }
    }

}

Notices

�q�是非常重要的一TemplateDirectiveModel对象通常不应该有状态�?/span> 典型的错误是对在该对象的字段指��o调用执行状态储存�?/span> 对同一指��o�Q�或者指令嵌套调用看成是由多个线�E�同时访问共享变量��用的对象�?br />
可惜的是�Q�TemplateDirectiveModel�Q�就做不支持传递参数按位置�Q�而不是名�U�ͼ��?/span> �q�是固定的�v价FreeMarker�?.4�?/span>

�C�物 2010-08-07 18:11 发表评论

Freemarker中��用OSCache

�C�物 — Sat, 07 Aug 2010 07:53:00 GMT

可以使用maven加入oscache依赖�Q�然后在需要��用oscache的freemarker��面上引入标�{?lt;#assign oscache=JspTaglibs['http://www.opensymphony.com/oscache']/>�Q�中括号中可以��用�\径方式，然后再页面上需要加入oscache的地方��?lt;@oscache:标记

例如�Q?br /><#assign oscache=JspTaglibs['http://www.opensymphony.com/oscache']/>

<#assign fowUrlaa="">
<#if RequestParameters.fowUrl?exists>
<#assign fowUrlaa="${RequestParameters.fowUrl}">

<@oscache.cache key="__oscache_categories" time=300>
${fowUrlaa}

然后再URL上添加参数测试：?fowUrl=12fas11