beetl-template

文章是对官方文档的摘录及在自己理解过程中对思路的整理。

简单的使用

引于依赖

1
2
3
4
5
6
<!-- https://mvnrepository.com/artifact/com.ibeetl/beetl -->
<dependency>
<groupId>com.ibeetl</groupId>
<artifactId>beetl</artifactId>
<version>2.9.3</version>
</dependency>

GroupTemplate

1
2
3
4
5
6
7
StringTemplateResourceLoader resourceLoader = new StringTemplateResourceLoader();
Configuration cfg = Configuration.defaultConfiguration();
GroupTemplate gt = new GroupTemplate(resourceLoader, cfg);
Template t = gt.getTemplate("hello,${name}");
t.binding("name", "beetl");
String str = t.render();
System.out.println(str);

Beetl的核心是GroupTemplate,是一个重量级对象,实际使用的时候建议使用单模式创建,创建GroupTemplate需要俩个参数,一个是模板资源加载器,一个是配置类,模板资源加载器Beetl内置了6种,分别是

  • StringTemplateResourceLoader:字符串模板加载器,用于加载字符串模板,如本例所示
  • FileResourceLoader:文件模板加载器,需要一个根目录作为参数构造,传入getTemplate方法的String是模板文件相对于Root目录的相对路径
  • ClasspathResourceLoader:文件模板加载器,模板文件位于Classpath里
  • WebAppResourceLoader:用于webapp集成,假定模板根目录就是WebRoot目录,参考web集成章
  • MapResourceLoader : 可以动态存入模板
  • CompositeResourceLoader 混合使用多种加载方式

代码第5行将变量name传入模板里,其值是“Beetl”。 代码第6行是渲染模板,得到输出,template提供了多种获得渲染输出的方法,如下

  • template.render() 返回渲染结果,如本例所示
  • template.renderTo(Writer) 渲染结果输出到Writer里
  • template.renderTo(OutputStream ) 渲染结果输出到OutputStream里

函数调用

beetl内置了少量实用函数,可以在Beetl任何地方调用。如下例子是调用date 函数,不传参数情况下,返回当前日期

示例:

1
2
3
4
5
6
7
StringTemplateResourceLoader resourceLoader = new StringTemplateResourceLoader();
Configuration cfg = Configuration.defaultConfiguration();
GroupTemplate gt = new GroupTemplate(resourceLoader, cfg);
Template t = gt.getTemplate("hello,${name}, <% println(date());%>");
t.binding("name", "beetl");
String str = t.render();
System.out.println(str);

安全输出

安全输出是任何一个模板引擎必须重视的问题,否则,将极大困扰模板开发者。
Beetl中,如果要输出的模板变量为null,则beetl将不做输出,这点不同于JSP,JSP输出null,也不同于Freemarker,如果没有用!,它会报错。

模板中还有俩种情况会导致模板输出异常

  • 有时候模板变量并不存在(譬如子模板里)
  • 模板变量为null,但输出的是此变量的一个属性,如${user.wife.name}

针对前俩种情况,可以在变量引用后加上以提醒beetl这是一个安全输出的变量。
可以在!后增加一个常量(字符串,数字类型等),或者另外一个变量,方法,本地调用,作为默认输出。

标签函数

所谓标签函数,即允许处理模板文件里的一块内容,功能等于同jsp tag。如Beetl内置的layout标签。

常见的是layout及include。标签函数可以用java代码自定义。

html标签

beetl的html标签包含一些规则。
主要使用方式以tag为后缀的文件被扫描到,然后可以在页面中以<#xx ></xx>方式引用。类似于jstl的自定义标签。不需要java代码,及参数传递要简单些。

直接调用java方法和属性

示例:

1
${@System.out.println(\"xxx\")}

Beetl小工具

BeetlKit 提供了一些便利的方法让你立刻能使用Beetl模板引擎。比如:

1
System.out.println(BeetlKit.render("${@System.out.println(\"xx\")}", null));

一行代码就可以体验模板的渲染

高级功能

配置GroupTemplate

Beetl建议通过配置文件配置GroupTemplate,默认配置在/org/beetl/core/beetl-default.properties 里,Beetl首先加载此配置文件,然后再加载classpath里的beetl.properties,并用后者覆盖前者。配置文件通过Configuration类加载,因此加载完成后,也可以通过此类API来修改配置信息。

配置文件示例:

1
2
3
4
5
6
RESOURCE_LOADER=org.beetl.core.resource.ClasspathResourceLoader
#资源配置,resource后的属性只限于特定ResourceLoader
#classpath 根路径
RESOURCE.root= /
#是否检测文件变化
RESOURCE.autoCheck= true

与web集成

web相关的全局变量

与jsp中的el表达式差不多,提供很多上下文相关的变量

Servlet集成

只需要在Servlet代码里引用ServletGroupTemplate就能集成Beetl,他提供了一个render(String child, HttpServletRequest request, HttpServletResponse response)方法。例子如下:

1
2
3
4
5
6
protected void doGet(HttpServletRequest request,HttpServletResponse response) throws ServletException, IOException {
response.setContentType("text/html;charset=UTF-8");
//模板直接访问users
request.setAttribute("users",service.getUsers());
ServletGroupTemplate.instance().render("/index.html", request, response);
}

ServletGroupTemplate同其他web集成一样,将读取配置文件来配置,如果需要通过代码配置,可以在Servlet listener里 ServletGroupTemplate.instance().getGroupTemplate()方法获取GroupTemplate

配置文件示例:
classpath中的beetl.properties,文件内容:

1
2
RESOURCE.root= /src/main/resources/template
RESOURCE.autoCheck= true

SpringMVC集成

总结

通篇的文档读下来,感觉到了beetl的使用方便及高度自定义。
在一些说明中,也感觉体现到beetl的设计想法。
这份文档,值得多读几次。