社区微信群开通啦,扫一扫抢先加入社区官方微信群
社区微信群
FreeMarker 是一款 模板引擎: 即一种基于模板和要改变的数据, 并用来生成输出文本(HTML网页,电子邮件,配置文件,源代码等)的通用工具。 它不是面向最终用户的,而是一个Java类库,是一款程序员可以嵌入他们所开发产品的组件。
模板编写为FreeMarker Template Language (FTL)。 在模板中,你可以专注于如何展现数据, 而在模板之外可以专注于要展示什么数据。 这种方式通常被称为 MVC (模型 视图 控制器) 模式,对于动态网页来说,是一种特别流行的模式。
上图如果Template换成Jsp,对于大多数JavaEE开发者来说,会显得非常熟悉。FreeMarker最初的设计,是被用来在MVC模式的Web开发框架中生成HTML页面的,它没有被绑定到 Servlet或HTML或任意Web相关的东西上。它也可以用于非Web应用环境中。 它完全可以替代Jsp,实现页面的静态化。
利用FreeMarker 实现一个网站用户登录显示用户信息。
FreeMarker 不依赖于web容器,所以普通的java项目也可以使用FreeMarker 。FreeMarker 的依赖包下载可以在官网进行获取,目前最新为FreeMarker 2.3.28版本。
利用IDEA创建工程,如果是普通项目则将 freemarker.jar
添加的 lib
目录下。如果创建为Maven项目,则可以在pom文件中添加:
<dependency>
<groupId>org.freemarker</groupId>
<artifactId>freemarker</artifactId>
<version>2.3.28</version>
</dependency>
如果是结合Spring使用FreeMarker,则需要额外添加依赖:
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context-support</artifactId>
<version>${spring.version}</version>
</dependency>
首先,需要创建一个 freemarker.template.Configuration
实例, 然后对其属性进行设置。Configuration
实例是存储 FreeMarker 应用级设置的核心部分。同时,它也处理创建和缓存预解析模板(比如 Template
对象)的工作。
Configuration
的创建代价很高,不需要重复创建实例,尤其是会丢失缓存。Configuration
实例就是应用级别的单例,不管一个系统有多少独立的组件来使用 FreeMarker, 它们都会使用他们自己私有的 Configuration
实例。
只需要在应用(可能是servlet)生命周期的开始执行一次:
// 创建Configuration实例,指定版本
Configuration configuration = new Configuration(Configuration.getVersion());
try {
// 指定configuration对象模板文件存放的路径
configuration.setDirectoryForTemplateLoading(new File("/where/you/store/templates"));
// 设置config的默认字符集,一般是UTF-8
configuration.setDefaultEncoding("UTF-8");
// 设置错误控制器
configuration.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
} catch (IOException e) {
e.printStackTrace();
}
关于错误控制器,FreeMarker 四个预先编写的错误控制器:
在 /where/you/store/templates
文件夹下创建模板文件 hello.ftl
。
<html>
<head>
<title>欢迎 ${user.username}!</title>
</head>
<body>
<h1>欢迎 ${user.username}!</h1>
<h2>年龄: ${user.age}</h2>
<h2>${user.record.id}:${user.record.name}</h2>
</body>
</html>
模板代表了 freemarker.template.Template
实例。 典型的做法是直接使用 Configuration
实例的 getTemplate()
方法获取一个 Template
实例,例如:
// 获取模版
Template template = configuration.getTemplate("hello.ftl");
当调用这个方法的时候,将会创建一个 hello.ftl
的 Template
实例,通过读取 */where/you/store/templates/hello.ftl
文件,之后解析(编译)它。Template
实例以解析后的形式存储模板, 而不是以源文件的文本形式。
Configuration
会缓存 Template
实例,当需要再次获得 hello.ftl
的时候,它可能不再读取和解析模板文件了, 而只是返回第一次获取的 Template
实例。
需要给模板的数据往往来自真实的业务数据,可能从数据库、文件等获得。在JavaEE中往往有单独的Service和Dao层帮助我们准备好需要的数据。数据的包装形式往往是JavaBean。
java.lang.String
来构建字符串。java.lang.Number
来派生数字类型。java.lang.Boolean
来构建布尔值。java.util.List
或Java数组来构建序列。java.util.Map
来构建哈希表。这里我们定义两个类,一个是User类,一个是用户记录Record类。
public class User {
private String username;
private int age;
private Record record;
/** setter and getter **/
}
public class Record {
private long id;
private String name;
/** setter and getter **/
}
下面是构建这个数据模型的Java代码片段:
// 准备数据
Map<String, User> map = new HashMap<>();
Record record = new Record();
record.setId(1L);
record.setName("记录一");
User user = new User();
user.setUsername("小明");
user.setAge(18);
user.setRecord(record);
map.put("user", user);
数据模型+模板=输出,这一过程是由模板的 process
方法完成的。它需要数据和 Writer
对象两部分作为参数,然后向 Writer
对象写入产生的内容。这里创建一个Writer对象,指定生成的文件保存的路径及文件名:
// 创建一个Writer对象,指定生成的文件保存的路径及文件名
Writer writer = new FileWriter(new File("/where/you/store/outputs"));
template.process(map, writer);
这里用到了Java IO相关的操作,基于 out
对象,必须保证 out.close()
最后被调用。典型的Web应用程序中,不能关闭 out
对象,对此FreeMarker会在模板执行成功后调用 out.flush()
,所以不必担心 (这一功能也可以在 Configuration
中禁用) 。
还有一点,一旦获得了 Template
实例, 就能将它和不同的数据模型进行不限次数的合并。此外, 当 Template
实例创建之后的模板文件 (hello.ftl
) 才能访问,而不是在调用 process
方法时。
FreeMarker 无法直接对布尔型的值直接输出True、False,需要对其format才能输出。
${布尔变量名?string('yes', 'no')}
FreeMarker 对Java的Date类型对象取值分两种情形,当用的sql包下的Date可以直接取值;当用的是util包下的Date则需要进行format才能输出。因为Java API通常不区别 java.util.Date
只存储日期部分, 时间部分,或两者都存。 为了用本文正确显示值,FreeMarker必须知道 java.util.Date
的日期究竟要显示哪一部分。
${sqldate}
${utildate?string("yyyy/MM/dd HH:mm:ss")}
FreeMarker 不可以输出null,类似于空指针异常。同样,如果通过 ${变量名}
表达式取值,压根不存在变量名,FreeMarker也会报出错误。 FreeMarker 对此加入了判空操作,利用 !
可以在null或missing的情况下不输出或输出默认文本。
${nullVar!'默认输出'}
${missingVar!}
通过assign标签给变量进行赋值,赋值完的变量可以在 ${}
中进行相应的运算。
<#assign a=100 />
<#assign b=2 />
a + b = ${a + b}
a - b = ${a - b}
a x b = ${a * b}
a / b = ${a / b}
a % b = ${a % b}
FreeMarker 可以采用list标签遍历Java中的List集合数据来输出文本,极为方便。
<#list numList as item>
list:${item}
</#list>
FreeMarker 也可以利用list标签来遍历map集合。需要取到map中的key,再通过key来取出相应的value。取map中的key可以通过 map?keys
来获取:
<#list objectMap?keys as key>
${key}:${objectMap[key].username}
</#list>
FreeMarker 提供了逻辑判断,采用if和else标签实现。满足条件则输出,不满足则忽略。
<#list numList as item>
<#if item!=2 >
list:${item}
</#if>
</#list>
<#list numList as item>
<#if item > 3 >
<font color="red">list:${item}</font>
<#elseif item == 3>
<font color="blue">list:${item}</font>
<#else>
<font color="green">list:${item}</font>
</#if>
</#list>
其中>;是大于的转义,同样<;是小于的转义。利用双问号 ??
或者 ?exists
可以对对象进行判空,例如:
<#if item??>
<#if item?exists>
同样FreeMarker 也支持多条件判断,用 &&
、||
、!
进行连接。
FreeMarker 的switch和Java中的switch十分类似,同样由switch、case、break和default标签组成。switch标签支持数值和字符串两种类型。
<#assign str="java" />
<#switch str>
<#case "python"> 学习python <#break>
<#case "java"> 学习java <#break>
<#default> 学习别的。。。
</#switch>
<#assign str="11.1" />
<#switch str>
<#case "11.1"> 学习python <#break>
<#case "11.11"> 学习java <#break>
<#default> 学习别的。。。
</#switch>
<#assign a="hello"/>
<#assign b="world"/>
<li>连接</li>
${a + b}
<li>截取</li>
${(a + b)?substring(5, 8)}
<li>长度</li>
${(a + b)?length}
<li>大写</li>
${(a + b)?upper_case}
<li>小写</li>
${(a + b)?lower_case}
<li>index</li>
${(a + b)?index_of('o')}
<li>last_index</li>
${(a + b)?last_index_of('o')}
<li>替换</li>
${(a + b)?replace('o', 'xx')}
<#assign myList=[3, 4, 5, 6, 1, 3, 7, 9, 2] />
mySize大小:${myList?size}
mySize第三个元素:${myList[3]}
顺序:
<#list myList?sort as item>
${item_index} : ${item}
</#list>
逆序:
<#list myList?sort?reverse as item>
${item_index} : ${item}
</#list>
处理字符串:
处理数字:
处理list:
其他:
在FreeMarker内部中可用的变量都是实现了freemarker.template.TemplateModel
接口的Java对象,而我们可以使用基本的Java集合类作为变量,是因为FreeMarker提供了一种对象包装的功能特性,我们用的基本的Java集合类变量会在内部被替换为适当的 TemplateModel
类型。
在自定义函数和指令中,我们需要使用FreeMarker中的数据类型,而非直接使用Java中的数据类型,所以有必要先熟悉FreeMarker中定义了哪些数据类型。
FreeMarker中定义了四种类型标量:布尔值,数字,字符串以及日期。每一种标量都是 TemplateXxxModel
接口的实现,Xxx
是Java中相关类型的名称。比如 TemplateBooleanModel
。这些接口中都只定义了一个方法用于转换类型为Java类型:getAsXxx()
。在名称上,只有字符串标量有些例外,字符串标量的接口是 TemplateScalarModel
,而不是TemplateStringModel
。
除了 SimpleBoolean
类型,这些接口的一个简单的实现是 freemarker.template
包下的 SimpleXxx
类。为了代表布尔值, 可以使用 TemplateBooleanModel.TRUE
和 TemplateBooleanModel.FALSE
来单独使用。 同样,字符串标量的实现类是 SimpleScalar
,而不是 SimpleString
。
除了标量,对于Java的集合数组类型FreeMarker也定义了相关的数据类型称为容器。容器包括哈希表,序列 和集合三种类型。
哈希表
哈希表是实现了 TemplateHashModel
接口的Java对象。TemplateHashModel
有两个方法: TemplateModel get(String key)
方法根据给定的名称返回子变量, boolean isEmpty()
方法表明哈希表是否含有子变量。get
方法当在给定的名称没有找到子变量时返回null。
TemplateHashModelEx
接口扩展了 TemplateHashModel
。它增加了更多的方法,使得可以使用内建函数 values 和 keys 来枚举哈希表中的子变量。
经常使用的实现类是 SimpleHash
,该类实现了 TemplateHashModelEx
接口。从内部来说,它使用一个 java.util.Hash
类型的对象存储子变量。 SimpleHash
类的方法可以添加和移除子变量。 这些方法应该用来在变量被创建之后直接初始化。
序列(数组)
序列是实现了 TemplateSequenceModel
接口的Java对象。它包含两个方法:TemplateModel get(int index)
和 int size()
。
经常使用的实现类是 SimpleSequence
。该类内部使用一个 java.util.List
类型的对象存储它的子变量。 SimpleSequence
有添加子元素的方法。 在序列创建之后应该使用这些方法来填充序列。
集合
集合是实现了 TemplateCollectionModel
接口的Java对象。这个接口定义了一个方法: TemplateModelIterator iterator()
。TemplateModelIterator
接口和 java.util.Iterator
相似,但是它返回 TemplateModels
而不是 Object
, 而且它能抛出 TemplateModelException
异常。
通常使用的实现类是 SimpleCollection
。
有时候FreeMarker内建函数不一定能够满足我们的处理需要,我们可以自定义函数来处理数据并展示。FreeMarker自定义函数需要自定义处理数据的类,该类需要实现 TemplateMethodModel
接口 ,接口中的 TemplateModel exec(java.util.List arguments)
方法也需要我们重新实现。当调用自定义函数时,自定义类的exec
方法将会被调用。 形参将会包含FTL方法调用形参的值。exec
方法的返回值给出了FTL方法调用表达式的返回值。
我们以自定义一个数组排序的函数为例,首先新建一个 MySortMethod
类实现 TemplateMethodModel
接口,并重写 exec
方法。
public class MySortMethod implements TemplateMethodModelEx {
/**
* 自定义函数需要实现的方法
* @param list 在.ftl模板中调用自定义方法传的参数
* @return 返回结果
* @throws TemplateModelException
*/
@Override
public Object exec(List list) throws TemplateModelException {
// 接收传入的List
DefaultListAdapter defaultListAdapter = (DefaultListAdapter) list.get(0);
List<Integer> arrayList = (List<Integer>) defaultListAdapter.getAdaptedObject(Integer.class);
// 接收传入的升序还是降序布尔值
boolean asc = "yes".equals(((SimpleScalar) list.get(1)).getAsString()) ? true : false;
Collections.sort(arrayList, new Comparator<Integer>() {
@Override
public int compare(Integer o1, Integer o2) {
if(asc) {
return o1 - o2;
}else {
return o2 - o1;
}
}
});
return arrayList;
}
}
在调用函数前,我们需要在模板数据里添加:
List<Integer> list = new ArrayList<>();
for (int i = 0; i < 5; i++) {
list.add(i+1);
}
map.put("numList", list);
map.put("my_sort", new MySortMethod());
在模板中调用自定义函数 my_sort
,传入两个参数:
顺序:
<#list my_sort(numList, true?string('yes', 'no')) as item>
${item_index} : ${item}
</#list>
逆序:
<#list my_sort(numList, false?string('yes', 'no')) as item>
${item_index} : ${item}
</#list>
输出结果为:
注:新版本的Api好像不太一样,在 MySortMethod.java
的13、14行中获取传入的list参数部分,我这里的写法是临时摸索出来的,有知道正确的获取list数据姿势的请不吝赐教。
类似自定义函数,我们也可以自定义指令,类似于if-else、assign这样的指令。自定义指令的需要使用 @
符号,而不是 #
符号。可以使用 TemplateDirectiveModel
接口在Java代码中实现自定义指令。TemplateDirectiveModel
在 FreeMarker 2.3.11 版本时才加入, 来代替快被废弃的 TemplateTransformModel
。
下面举个栗子,自定义用来校验用户名密码的指令:
public class MyValidationDirective implements TemplateDirectiveModel {
/**
*
* @param environment 环境变量(实现复杂功能时可能会用)
* @param map 在.ftl模板中使用自定义指令传的参数(key-value形式)
* @param templateModels 返回值,数组形式
* @param templateDirectiveBody 指令内容
* @throws TemplateException
* @throws IOException
*/
@Override
public void execute(Environment environment,
Map map,
TemplateModel[] templateModels,
TemplateDirectiveBody templateDirectiveBody)
throws TemplateException, IOException {
SimpleScalar username = (SimpleScalar) map.get("username");
SimpleScalar password = (SimpleScalar) map.get("password");
if("admin".equals(username.getAsString()) && "123456".equals(password.getAsString())) {
templateModels[0] = TemplateBooleanModel.TRUE;
} else {
templateModels[0] = TemplateBooleanModel.FALSE;
}
List<String> rights = new ArrayList<>();
rights.add("insert");
rights.add("delete");
rights.add("update");
rights.add("select");
templateModels[1] = new SimpleSequence(rights);
templateDirectiveBody.render(environment.getOut());
}
}
模板编写:
利用 <@role />
标签需要传入模版数据前进行添加:
map.put("role", new MyValidationDirective());
或者在模板文件中使用内建函数 new()
将指令放到一个FTL库中:
<#assign role="directive.MyValidationDirective"?new() />
输出结果:
macro语法:
<#macro 指令名称 param1 param2 param3 paramN>
template_code 可以获取参数${param1}
<#nested />
</#macro>
调用语法:
<@指令名称 param1="xxx" param2="xxx" />
<@指令名称 param1="xxx" param2="xxx">
nested_template
</@指令名称>
下面举一些例子。
<h2>无参数的macro</h2>
<#macro test1>
我是无参数的macro
</#macro>
<@test1 />
<h2>有参数的macro</h2>
<#macro test2 param1 param2>
我是有参数的macro,参数是${param1}和${param2}
</#macro>
<@test2 param1="hello" param2="world"/>
<h2>有默认参数的macro</h2>
<#macro test3 param1 param2="world">
我是有默认参数的macro,参数是${param1}和${param2}
</#macro>
<@test3 param1="hello" />
<@test3 param1="hello" param2="earth"/>
<h2>有多个参数的macro</h2>
<#macro test4 param1 param2 paramExt...>
我是有多个参数的macro,参数是${param1}、${param2}、${paramExt['param3']}和${paramExt['param4']}
</#macro>
<@test4 param1="hello" param2="world" param3="hi" param4="man"/>
<h2>有nested的macro</h2>
<#macro test5 param1 param2="hi" paramExt...>
我是有多个参数的macro,固定参数是${param1}和${param2}
<#nested paramExt['param3'] paramExt['param4']/>
</#macro>
<@test5 param1="hello" param2="world" param3="hi" param4="man"; loopVar1, loopVar2>
可变参数为${loopVar1}和${loopVar2}
</@test5>
function语法:
<#function 方法名 param1 param2>
<#return param1和param2的操作>
</#function>
调用语法:
${方法名(param1, param2)}
下面举一些例子。
<#function doAdd param1 param2>
<#return param1+param2 />
</#function>
${doAdd(2, 3)}
输出为5。
以商城项目生成商品详情页面为例,一般访问url中每个商品id有个静态页面,例如京东商品页面。每个商品静态页面可以利用FreeMarker来生成。
Spring要结合FreeMarker需要在配置文件中进行配置Configration。
<!--配置FreeMarker-->
<bean id="freemarkerConfig"
class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
<property name="templateLoaderPath" value="/WEB-INF/ftl/" />
<property name="defaultEncoding" value="UTF-8" />
</bean>
/**
* 生成静态页面Service
*/
public class StaticPageServiceImpl implements StaticPageService {
@Autowired
private ItemService itemService;
@Autowired
private FreeMarkerConfig freeMarkerConfig;
@Value("${STATIC_PAGE_PATH}")
private String STATIC_PAGE_PATH;
@Override
public TaotaoResult getHtml(Long itemId) throws IOException, TemplateException {
// 获取商品基本信息、详细介绍和商品参数
TbItem tbItem = itemService.getItemById(itemId);
String desc = itemService.getItemDescById(itemId);
String param = itemService.getItemParamById(itemId);
// 生成静态页面
Configuration configuration = freeMarkerConfig.getConfiguration();
Template template = configuration.getTemplate("item.ftl");
Map<String, Object> root = new HashMap<>();
root.put("item", tbItem);
root.put("itemDesc", desc);
root.put("itemParam", param);
Writer writer = new FileWriter(new File(STATIC_PAGE_PATH + itemId + ".html"));
template.process(root, writer);
writer.flush();
writer.close();
return TaotaoResult.ok();
}
}
模版文件的准备仅仅需要将jsp或html文件修改成ftl模板即可。
生成好的静态html文件,可以利用Nginx服务器进行部署,这样性能比Tomcat要好,其次也不需要各种延迟加载等操作。
如果觉得我的文章对您有用,请随意打赏。你的支持将鼓励我继续创作!