转:Beetl-Spring扩展文档
本文是Beetl模板引擎的Spring整合扩展的使用文档
beetl-spring源码和使用示例的发布在这里 https://git.oschina.net/shishuifox/beetl-spring
beetl的官网在这里 http://ibeetl.com
一、GroupTemplateFactoryBean
GroupTemplateFactoryBean实现了FactoryBean<GroupTemplate>接口，是Beetl核心类GroupTemplate的工厂Bean。
相对于Beetl自带的BeetlGroupUtilConfiguration，他的优势在不依赖Spring Web应用程序上下文环境，能产生被Spring容器管理的GroupTemplate对象，能对GroupTemplate做更丰富的配置，在一般Spring应用中也能正常使用，配置方法如下：
1 |
<bean name="groupTemplate" class="org.fox.beetl.ext.spring.GroupTemplateFactoryBean"/>
|
1.1 配置参数
GroupTemplateFactoryBean所有参数都不是必须的，他有以下参数：
| 参数名 | 说明 |
| configFileResource |
指定Beetl配置文件，这里的文件指定采用Spring Resource语法： 1. Classpath访问（以classpath:为前缀），例如：classpath:beetl.properties 表示在当前类路径下找配置文件 Classpath访问是非Web的Spring上下文的默认资源访问方式。 2. URL访问，支持http ftp file等，只要Java的URLConnection支持的协议均可，特殊的可以用file:为前缀访问文件系统：file:beetl.properties表示当前目录下的beetl.properties也可以用绝对路径 3.ServletContext访问，在Spring Web上下文中，以/开头（无任何前缀）的路径是访问当前Web工程下的文件如 /WEB-INF/beetl.properties ServletContext访问是Spring Web 上下文的默认资源访问方式 Spring Resource机制详细参见：Spring官方文档 beetl-spring的配置文件加载机制参见本文档 1.2节。 |
| configProperties | 用于覆盖Beetl配置文件的Properties对象 beetl-spring的配置文件加载机制参见本文档 1.2节。 |
| resourceLoader | Beetl 资源加载器 |
| errorHandler | Beetl异常处理器 |
| sharedVars | Beetl共享变量，可以为他注入一个在Bean定义文件中定义的map，也可以使用Spring util命名空间配置直接加载一个properties为共享变量赋值 |
| functions | 自定义函数，key为注册时的函数名 |
| typeFormats | 自定义类型默认格式化器，key为格式化器对应的类型Class |
| formats | 自定义格式化器，key为注册时的格式化器名 |
| tagFactorys | 自定义标签工厂，key为注册时的标签名 |
| functionPackages | 自定义函数包，key为注册时的函数包名 |
| virtualClassAttributes | 自定义虚拟属性 |
| virtualAttributeEvals | 自定义虚拟属性执行器 |
1.2 Beetl配置加载过程
对Beetl配置的加载取决于configFileResource和configProperties两个参数的配置，有下面几种情况：
1) 如果configFileResource和configProperties均未设置，这时获取默认Beetl配置，即默认加载classpath下beetl.properties文件；
2) 如果configFileResource有设置，则按照其设置加载配置数据。加载完成后如果configProperties有配置，就利用configProperties中的配置项覆盖配置文件的设置；
3) 如果configFileResource未设置，但有指定configProperties，则完全靠configProperties来配置Beetl。
1.3Beetl组件配置
GroupTemplateFactoryBean除了configFileResource和configProperties的其他参数旨在将Spring容器管理的Bean注册为Beetl组件（函数，格式化器，标签等），这样的Beetl组件能借助Spring的特性实现更强大的功能（例如IOC，AOP，事务支持，缓存支持，容器感知等），这样的一个范例即本扩展提供的SpELFunction，允许执行SpEL表达式并能直接引用Spring容器中的Bean，详情请参见本文3.1节。
二、Spring MVC视图类
2.1BeetlViewResolver 视图解析器
BeetlViewResolver是一个Spring MVC视图解析器实现，他配合BeetlView一起使用，提供Beetl视图支持。和Beetl自带的BeetlSpringViewResolver相比，他增强了视图类对GroupTemplate的配置，提供了GroupTemplate设置和多配置视图解析器支持。
注意：BeetlViewResolver必须调用初始化方法init()，建议Spring开启注解配置支持，这样初始化方法可以自动调用
1 |
<context:annotation-config/>
|
2 |
<bean name="beetlViewResolver" class="org.fox.beetl.ext.spring.BeetlViewResolver">
|
否则，我们需主动声明调用初始化方法
1 |
<bean name="beetlViewResolver" class="org.fox.beetl.ext.spring.BeetlViewResolver" init-method="init">
|
BeetlViewResolver常用属性如下(除groupTemplate外其他都来自Spring MVC)：
| 参数名 | 说明 |
| prefix, suffix | 视图前缀/后缀 这是Spring MVC UrlBasedViewResolver的特性 计算出的视图url = prefix + viewName + suffix; 默认没有前缀和后缀 |
| contentType | 生成的视图渲染返回Http相应包的Content-Type头，虽然不是强制设置，但是如果不想结果乱码的话，最好设置一下，如 text/html;charset=utf-8 |
| order | 视图解析器排序，在Spring上下文中如果有多个视图解析器，必须设置，值越小排序越靠前 默认为0 |
| viewNames | 带通配符*的视图名表达式数组，只有匹配其中之一的视图名才能被当前BeetlViewResolver处理 默认所有的视图名都能被当前ViewResolver处理 |
| groupTemplate |
注入BeetlViewResolver产生的BeetlView使用的groupTemplate 默认使用当前Spring上下文中唯一的groupTemplate，如果有多个groupTemplate时必须指定 |
关于Spring MVC的多视图解析的问题，这里多解说一下，如果Spring上下文中有多个Spring 视图解析器Bean，会按他们的order属性对他们进行排序，依次使用待处理的视图名调用这些视图解析器的canHandle()方法，直到某个视图解析器返回true，则将视图解析交给其处理；否则继续调用下一个解析器的canHandle()；BeetlViewResolver的canHandle()实现为检查待处理视图是否与viewNames属性匹配（一般都并不是检查模板文件是否存在）。
需要注意，在多视图解析器的情况下BeetlViewResolver必须排在Spring MVC自带的InternalResourceViewResolver之前(因为他的canHandle()总是返回true，会让BeetlViewResolver没有机会处理)。
利用多视图解析器配置和groupTemplate指定，我们可以方便的把项目中的beetl视图按功能配置分成多个BeetlViewResolver来处理。例如CMS系统中，用户上传的模板可能需要更强的安全控制，禁用本地调用，不提供SpEL函数等，友好且可调试的错误输出等；而对于CMS自带的后台管理页面用的模板，则可以放宽这些限制来谋求更强大的功能。这样不同的配置需求就可以得以实现。
2.2 BeetlView 视图类
BeetlView视图类没有什么特别说的，由BeetlViewResolver创建，使用BeetlViewResolver组装好的视图url显然Beetl视图并返回Http响应。
三、其他扩展
3.1 SpELFunction spel函数
SpELFunction函数类是Beetl的一个Function扩展，允许在Beetl中执行SpEL表达式，其调用格式为：
1 |
String spel(String expression) |
SpEL的相关内容请参见: Spring官方文档
特殊的这里支持使用@beanName的方式直接引用Spring上下文中的Bean对象，或者使用T(className).method()的方式调用指定类的静态方法，例如：
1 |
spel('@urlEncoder.encode(name)')
|
1 |
spel('T(java.util.UUID).randomUUID().toString()')
|
注意1：当前版本的SpELFunction只支持操作Beetl上下文中的共享变量和全局变量，不能访问页面内的临时变量。
注意2：SpELFunction必须作为Spring上下文中的Bean通过GroupTemplateFactoryBean的functions属性提供给Beetl，这个函数依赖Spring上下文。
3.2 SpringBeanTagFactory Spring Bean标签工厂
SpringBeanTagFactory按照name属性的设置从Spring上下文中获取Tag实现Bean作为标签的真正处理对象。他的name属性是必须设置的。它一般是作为一个TagFunction由GroupTemplateFunctionBean的tagFactorys属性注入提供给Beetl，例如：
1 |
<property name="tagFactorys">
|
2 |
<map>
|
3 |
<entry key="accessIf">
|
4 |
<bean class="org.fox.beetl.ext.spring.tag.SpringBeanTagFactory">
|
5 |
<property name="name" value="accessIfTag"/>
|
6 |
</bean>
|
7 |
</entry>
|
8 |
</map>
|
9 |
</property>
|
注意：需要非常注意的是他所引用的Tag Bean，必须是prototype的，不能单例，否则在并发使用时可能会有问题。
1 |
<bean name="accessIfTag" class="...." scope="prototype"/>
|