FreeMarker 2.3.19 模板开发与程序指南

需积分: 9 9 下载量 56 浏览量 更新于2024-07-29 收藏 4.46MB PDF 举报
"FreeMarker手册(用于2.3.19)" FreeMarker是一个强大的、开源的模板引擎,主要用于生成HTML或其他类型的文本输出,特别是在Web应用程序中作为视图层的技术。它与Java紧密集成,允许开发者使用模板来动态生成内容,而无需在Java代码中混杂大量的字符串拼接和条件逻辑。 在《FreeMarker手册》中,主要分为两大部分:模板开发指南和程序开发指南,旨在帮助开发者理解和使用FreeMarker进行模板设计和程序集成。 **前言** 这部分简要介绍了FreeMarker的基本概念和手册的阅读指南,以及文档的规约和联系作者的方式。 **第一部分:模板开发指南** 1. **模板开发入门** - 引入了FreeMarker的核心概念,即模板和数据模型的结合产生输出。 - 数据模型包括各种数据类型,如标量、容器、方法等。 - 模板由指令、表达式和插值组成,它们是构建模板的主要元素。 2. **数值和类型** - 讨论了FreeMarker中的基本内容和数据类型,包括如何处理数字、字符串和其他类型。 3. **模板** - 描述了模板的总体结构,包括如何组织指令、表达式以及插值。 - 指令用于控制模板的流程,如循环和条件语句。 - 表达式用于计算值,插值则是在文本中插入变量或表达式的值。 4. **其他** - 自定义指令允许开发者扩展FreeMarker的功能。 - 定义模板中的变量可以存储计算结果或中间状态。 - 命名空间用于组织和重用指令。 - 空白处理讨论了如何管理模板中的空格和换行。 - 替换(方括号)语法提供了另一种插入值到文本中的方式。 **第二部分:程序开发指南** 1. **程序开发入门** - 演示了如何创建FreeMarker的配置实例,加载数据模型,获取模板,并将两者合并生成输出。 - 这部分代码示例展示了如何在Java应用中集成FreeMarker。 2. **数据模型** - 详细阐述了数据模型的构成,包括标量、容器、方法、指令、节点变量和对象包装,这些都是构建数据模型的基础。 3. **配置** - 配置对象是FreeMarker的核心设置,包括模板的加载路径、缓存策略等。 手册还涵盖了更多高级主题,如模板继承、宏、日期和时间处理,以及错误处理等。对于任何希望深入理解并有效使用FreeMarker的人来说,这本手册都是一个宝贵的资源。通过学习这个手册,开发者可以熟练地创建高效的模板,实现灵活的动态内容生成。
2012-03-04 上传
FreeMarker 手册 .......................................................................................................... 1 用于 FreeMarker 2.3.18 ........................................................................................... 1 目录................................................................................................................................. 2 前言................................................................................................................................. 7 什么是FreeMarker? ................................................................................................. 7 我们应该阅读什么内容? .......................................................................................... 7 文档规约................................................................................................................... 8 联系我们................................................................................................................... 8 几点说明................................................................................................................... 8 第一部分 模板开发指南 ................................................................................................... 9 第一章 模板开发入门 ............................................................................................... 9 1.1 简介 ............................................................................................................ 9 1.2 模板 + 数据模型 = 输出 ............................................................................. 9 1.3 数据模型一览 ............................................................................................ 10 1.4 模板一览 ................................................................................................... 13 第二章 数值和类型 ................................................................................................. 19 2.1 基本内容 ................................................................................................... 19 2.2 类型 .......................................................................................................... 21 第三章 模板 ........................................................................................................... 25 3.1 总体结构 ................................................................................................... 25 3.2 指令 .......................................................................................................... 26 3.3 表达式 ....................................................................................................... 27 3.4 插值 .......................................................................................................... 42 第四章 其它 ........................................................................................................... 45 4.1 自定义指令 ................................................................................................ 45 4.2 在模板中定义变量 ..................................................................................... 50 4.3 命名空间 ................................................................................................... 53 4.4 空白处理 ................................................................................................... 56 4.5 替换(方括号)语法 ................................................................................... 59 第二部分 程序开发指南 ................................................................................................. 61 第一章 程序开发入门 ............................................................................................. 61 1.1 创建配置实例 ............................................................................................ 61 1.2 创建数据模型 ............................................................................................ 61 1.3 获得模板 ................................................................................................... 62 1.4 合并模板和数据模型 .................................................................................. 63 1.5 将代码放在一起 .......................................................................................... 63 第二章 数据模型 .................................................................................................... 65 2.1 基本内容 ................................................................................................... 65 2.2 标量 .......................................................................................................... 65 2.3 容器 .......................................................................................................... 66 2.4 方法 .......................................................................................................... 67 2.5 指令 .......................................................................................................... 68 2.6 节点变量 ................................................................................................... 74 2.7 对象包装 ................................................................................................... 75 第三章 配置 ........................................................................................................... 79 3.1 基本内容 ................................................................................................... 79 3.2 共享变量 ................................................................................................... 79 3.3 配置信息 ................................................................................................... 80 3.4 模板加载 ................................................................................................... 82 3.5 错误控制 ................................................................................................... 85 第四章 其它 ........................................................................................................... 89 4.1 变量 .......................................................................................................... 89 4.2 字符集问题 ................................................................................................ 89 4.3 多线程 ....................................................................................................... 91 4.4 Bean 的包装 ................................................................................................ 91 4.5 日志 .......................................................................................................... 97 4.6 在Servlet 中使用FreeMarker ...................................................................... 98 4.7 为FreeMarker 配置安全策略......................................................................105 4.8 遗留的XML 包装实现 ................................................................................106 4.9 和Ant 一起使用FreeMarker.......................................................................109 4.10 Jython 包装器 ..........................................................................................110 第三部分 XML 处理指南................................................................................................112 前言.......................................................................................................................112 第一章 揭示XML 文档 ...........................................................................................113 1.1 节点树 ......................................................................................................113 1.2 将XML 放到数据模型中 ............................................................................115 第二章 必要的XML 处理 ........................................................................................117 2.1 通过例子来学习 ........................................................................................117 2.2 形式化描述 ...............................................................................................124 第三章 声明的XML 处理 ........................................................................................129 3.1 基础内容 ..................................................................................................129 3.2 详细内容 ..................................................................................................131 第四部分 参考文档 .......................................................................................................134 第一章 内建函数参考文档 .....................................................................................134 1.1 处理字符串的内建函数 .............................................................................134 1.2 处理数字的内建函数 .................................................................................147 1.3 处理日期的内建函数 .................................................................................151 1.4 处理布尔值的内建函数 .............................................................................155 1.5 处理序列的内建函数 .................................................................................156 1.6 处理哈希表的内建函数 .............................................................................161 1.7 处理节点(XML)的内建函数....................................................................162 1.8 很少使用的和专家级的内建函数 ...............................................................163 第二章 指令参考文档 ............................................................................................167 2.1 if,else,elseif 指令 ...................................................................................167 2.2 switch,case,default,break 指令..............................................................169 2.3 list,break 指令 .........................................................................................170 2.4 include 指令 ...............................................................................................171 2.5 import 指令 ...............................................................................................174 2.6 noparse 指令 ..............................................................................................175 2.7 compress 指令 ............................................................................................176 2.8 escape,noescape 指令...............................................................................177 2.9 assign 指令 ................................................................................................179 2.10 global 指令 ..............................................................................................181 2.11 local 指令 ................................................................................................182 2.12 setting 指令 .............................................................................................182 2.13 用户自定义指令(<@...>) ......................................................................184 2.14 macro,nested,return 指令 ....................................................................186 2.15 function,return 指令...............................................................................190 2.16 flush 指令 ................................................................................................192 2.17 stop 指令.................................................................................................192 2.18 ftl 指令 ....................................................................................................193 2.19 t,lt,rt 指令 ..........................................................................................194 2.20 nt 指令 ....................................................................................................195 2.21 attempt,recover 指令 .............................................................................196 2.22 visit,recurse,fallback 指令 .....................................................................197 第三章 特殊变量参考文档 .....................................................................................202 第四章 FTL 中的保留名称.......................................................................................204 第五章 废弃的FTL 结构 .........................................................................................205 5.1 废弃的指令列表 ........................................................................................205 5.2 废弃的内建函数列表 .................................................................................205 5.3 老式的macro 和call 指令 ..........................................................................205 5.4 转换指令 ..................................................................................................207 5.5 老式FTL 语法 ............................................................................................208 5.6 #{…}式的数字插值 ......................................................................................209 第五部分 附录 ..............................................................................................................211 附录A FAQ .............................................................................................................211 1. JSP 和FreeMarker 的对比 .............................................................................211 2. Velocity 和FreeMarker 的对比.......................................................................212 3. 为什么FreeMarker 对null-s 和不存在的变量很敏感,如何来处理它? ......212 4. 文档编写了特性X,但是好像FreeMarker 并不知道它,或者它的行为和文档描 述的不同,或者一个据称已经修改的BUG 依然存在。 .....................................213 5. 为什么FreeMarker 打印奇怪的数字数字格式(比如1,000,000 或1 000 000 而不 是1000000)? ...............................................................................................213 6. 为什么FreeMarker 会打印不好的小数和/或分组分隔符号(比如3.14 而不是3,14) .......................................................................................................................214 7. 为什么当我想用如格式打印布尔值时,FreeMarker 会抛出错误,又如何来修正 呢?................................................................................................................214 8. FreeMarker 标签中的<和>混淆了编辑器或XML 处理器,应该怎么做? .........214 9. 什么是合法的变量名? ...............................................................................214 10. 如何使用包含空格,或其他特殊字符的变量(宏)名? ............................215 11. 当我试图使用JSP 客户标签时为什么会得到非法参数异常:形式参数类型不匹 配?................................................................................................................215 12. 如何像jsp:include 一样的方式引入其它的资源?................................216 13. 如何给普通Java 方法/ TemplateMethodModelEx/ TemplateTransformModel/ TemplateDirectiveModel 的实现传递普通 java.lang.* / java.util.*对象的参数? ...............................................216 14. 为什么在myMap[myKey]表达式中不能使用非字符串的键?那现在应该怎么 做?................................................................................................................217 15. 当使用?keys/?values 遍历Map(哈希表)的内容时,得到了混合真正map 条目的java.util.Map 的方法。当然,只是想获取map 的条目。 ...............218 16. 在FreeMarker 的模板中如何改变序列(lists)和哈希表(maps)? ...........218 17. 关于null 在FreeMarker 模板语言是什么样的? ......................................219 18. 我该怎么在表达式(作为另外一个指令参数)中使用指令(宏)的输出? 220 19. 在输出中为什么用“?”来代替字符X? ..................................................220 20. 在模板执行完成后,怎么在模板中获取计算过的值? ................................221 21. 我能允许用户上传模板吗?又如何保证安全呢? .......................................221 22. 如何在Java 语言中实现方法或宏而不是在模板语言中?............................222 23. 为什么FreeMarker 的日志压制了我的应用程序? ......................................222 24. 在基于Servlet 的应用程序中,如何在模板执行期间发生错误时,展示一个友 好的错误提示页面,而不是堆栈轨迹? ...........................................................223 25. 我正使用一个可视化的HTML 割裂模板标记的编辑器。你们可以改变模板语言 的语法来兼容我的编辑器么? .........................................................................223 26. FreeMarker 有多快?真的是2.X 版本的要比1.X 版本(经典的FreeMarker)的慢 吗?................................................................................................................223 27. 我的Java 类怎么才能获取到关于模板结构的信息(比如所有变量的列表)? .......................................................................................................................224 28. 你会一直提供向后的兼容性吗? ...............................................................224 29. 如果我们把FreeMarker 和我们的产品一起发行,我们需要发布我们产品的源代 码么? ............................................................................................................225 附录B 安装FreeMarker..........................................................................................226 附录C 构建FreeMarker..........................................................................................227 附录D 版本 ...........................................................................................................228