Skip to content

Instantly share code, notes, and snippets.

@xiuhy
Last active August 24, 2017 03:45
Show Gist options
  • Save xiuhy/35b63268a98d2f16ffbd10f54d47cafb to your computer and use it in GitHub Desktop.
Save xiuhy/35b63268a98d2f16ffbd10f54d47cafb to your computer and use it in GitHub Desktop.
freemarker 学习笔记

freeMarker 笔记

[TOC]

freeMarker 类型

标量

  • 字符串
  • 数字 不区分整数和非整数。统一为数字类型
  • 布尔值
  • 日期 只有三种显示,time,date,date_time。可以通过配置确定显示格式

freeMarker 是区分数字,字符串和布尔值类型。

容器

  • 哈希表 类似Java中hashMap
  • 序列 类似数组,下标从0开始
  • 集合 有限制的序列,但是不能获取集的大小,也不能通过索引获取子变量。可以通过list 遍历

注意项

总体结构

  1. ftl 区分大小写
  2. 插值(${..})只能再文本和字符串表达式中使用
  3. ftl 标签 不可以再其他ftl标签和插值中使用
  4. 注释可以再标签和插值中使用
  5. freemakrer "空格剥离"作用,去除多余的空格,制表符和换行符

检测不存在值

  1. expression!defaultValue
  2. expression?? 存在tree,反之false

布尔值插入

1.不要使用插入方式打印布尔值。可以使用${variable?string("yes","no")} 2. 如果freemarker,再传统兼容模式下,如果值是布尔类型,true就显示true,false显示空字符串

指令

常规标签语法格式:

<#name parameter> </#name>

  • 没有嵌套内容必须<#name/>
  • 指令包括两种类型:1.ftl自带类型;2. 用户自定义,用@代替#
  • 通过配置,可以使用[ ]代替{}
  • 通过配置,可以去除#(不建议)

字符串操作

插值

  • 可以在字符串中使用${...}
  • ${"xx"+ddd}
  • ${"xxx ${ddd}"}

序列操作

  1. 连接 [xxx,x,x,x]+[xxx,xx,x]

  2. 分割 截取:[startIndex,endIndex],两边全包含

哈希

  1. 连接+ 加号右侧的哈希表项目优先(覆盖)

算数运算

  1. 展示整数部分 xx?int 可以直接强转成整数(不四舍五入,只去除小数部分)
  2. 比较时,>,<请加入小括号或者用转义字符表示。否则不正确

函数vs指令:

  • 函数返回可以自动xml转义(${...})特性。用户自定义<@...>不转义
  • 指令没有返回值
  • 指令可以流程控制,方法/函数不可以

内建函数

内建函数是以?形式提供变量不同形式或者其他信息。

xx?expression

内建函数:

  • 字符串内建函数
    • ??(测试没效果)html.字符串中所有的特殊html字符串需要用实体引用来代替。比如 < 代替<
    • cap_first: 字符串首字母大写;uncap_first:首字母小写
    • lower_case 转小写
    • upper_case 转大写
    • trim 去掉字符串收尾空格
    • substring 取子串 exp?substring(from,[toExclusive]).包左不包右.如参数不是整数,则使用整数使用
    • capitalize 首字母大写。字符串中所有单词首字母大写,有别于cap_first
    • 字符串转换成日期值 date(expr)
    • 字符串转换成日期值 time(expr)
    • 字符串转换成日期值 datetime(expr)

注:日期格式必须和字符日期格式一致。转换日期格式是按照freemarker配置来,和expr没关系(感觉好鸡肋) - end_with(expr) 判断是否以指定结尾

  • 数字内建函数

    • c 数字转换成字符串
    • string 数字转换成字符串:四种预定义格式
      • computer
      • currency 有四舍五入效果
      • number
      • percent
      • string(expr), 使用java DecimalForamt格式. e.g:#.##
    • round 返回最近的整数(四舍五入)
    • floor 返回舍掉小数后的整数(向负无穷)
    • ceiling 返回小数进位后的整数(向正无穷)
    • int 数字整数部分
  • 日期内建函数 通过freemarker配置就可以实现日期格式

    • short 对时间,日期,时间日期四种显示格式
    • medium 对时间,日期,时间日期四种显示格式
    • long 对时间,日期,时间日期四种显示格式
    • full 对时间,日期,时间日期四种显示格式
    • iso:显示指定时区时间。已经在2.3.21版本中废弃。详见官网
  • 布尔值内建函数

    • c 返回true,或者false.基于v2.3.20版本
    • string true 返回“true”,false返回“false”
    • string(trueExpr,falsExpr) true 返回trueExpr,false返回falseExpr
  • 序列内建函数

    • size 元素个数
    • first 获取第一个项
    • last 获取最后一个项
    • seq_contains 序列包含
    • seq_index_of 第一次出现的位置,从0开始
    • seq_index_of 最后一次出现的位置,从0 开始
    • reverse 反转序列。返回还是序列
    • sort 升序排序。item类型必须一致
    • sort_by 以。。。来升序排序。和sort一样,除了子项必须是哈希类型
    • chunk(count,[flag]).将序列等分分成,最后一个大小不定。flag参数可以补充
  • 哈希内建函数

    • keys 获取所有哈希表key
  • 节点(xml)内建函数(后续)

  • 高级内建函数(使用率低)

    • byte,double float,int,long,short 数字类型强行转换
    • number_date,number_to_time,number_to_datetime long类型的时间转换成日期类型
    • eval 求值
    • has_content 是否有内容。如果变量(不是java的null)存在且不是空,则返回true,反之返回false
    • interpret 将字符串解释为ftl模版(暂时不考虑)
    • is... 判断函数族
      • is_string 是否是字符串
      • is_number 是否是数字
      • is_boolean 是否是布尔值
      • is_date 是否是日期
      • is_method 是否是方法
      • ?is_transform 是否是变换
      • ?is_macro 是否是宏
      • is_hash 哈希表
      • is_hash_ex 扩展的哈希表(也就是支持?keys 和?values)
      • is_sequence 序列
      • is_collection 集合
      • is_enumerable 序列或集合
      • is_indexable 序列
      • is_directive指令的类型(比如宏,或 TemplateDirectiveModel ,TemplateTransformModel 等)
      • is_node 节点

指令参考文档

if else elseif

语法:

<#if condition> ...... <#elseif condition2> ...... <#else> ...... </#if>

注:conditon 是判断条件,最终输出是boolean类型

switch

语法

<#switch value> <#case refValue>.....<#break> ........ <#default> ...... </#switch>

value,refValue 必须是相同类型数据。官方不建议使用。详见

list

语法: A

<#list sequence as item> ............ </#list>

B

<#list value1..value2 as item> </#list>

注:这里还有两个隐含变量:item_index;item_has_next;前者表示当前项再循环中的步值(0开始); 后者是判断是否有下一个值,返回boolean类型。 这里item_index item是和list标签中list必须一致名称 list 可以特定数字集合使用..,value1,value2 是开始结束数字,类型必须为数字类型

include path option

path:字符串 options encoding: 字符串表达式:ISO-8859-2,UTF-8,Shift_JIS,Big5,EUC-KR,GB2312 parse: 布尔表达式。true 会ftl解析被加载的文档,反之不解析ftl

将被include文件添加到当前模版中,共享变量。

import

语法:

<#import path as hash>

引入一个库,并创建一个新命名空间。 path:模版导入路径,可以是相对和绝对 hash:创建一个命名空间。多次引入同一个路径的命名空间只会按照第一个有效。

noparse

语法

<#noparse> ......... </#noparse>

freekMarker 不会再这个标签中解析ftl标签,插值,和其他特殊字符。 parse 标签相反功能

compress(废弃)

语法:

<#compress> .... </#compress>

将标签内不的多余空格,换行移除,但是不改变原来换行效果

assign

使用这个指令你可以创建一个新的变量,或者替换一个已经存在的变量

<#assign name=value>

<#assign name1=v1 name2=v2>

<#assign name> ....</#assign>

<#assign name in namespace>....</#assign>

name:变量名称 value:变量值 namespace: 通过import为命名空间创建的哈希表

global

语法:和assign语法一致 赋值全局变量。所有命名空间都可以访问该变量。如果局部变量名相同,则覆盖。 可以通过${.globals.x}获取被隐藏的值

local

语法:和assign语法类似 但是它创建或替换局部变量。这仅仅在宏和方法的内部定义 才会有作用。

setting

语法

<#setting name=value>

为进一步的处理而设置。设置是影响 FreeMarker 行为的值。新值仅仅在被设置的模板 处理时出现,而且不触碰模板本身。

  • locale:输出本地化语言。影响数字,日期显示格式。 由语言编码(两位)和国家编码(两位)组成
  • number_format
  • boolean_format 以逗号分隔的一对字符串来分别展示 true 和 false 值,当 没有指定确定的格式时,转换布尔值到字符串。默认值是"true,false"
  • date_format,time_format,datetime_format
  • time_zone:时区的名称来显示并格式化时间。默认情况下,使用系统的时区。 也可以是 Java 时区 API 中的任何值。比如: "GMT", "GMT+2", "GMT-1:30", "CET","PST","America/Los_Angeles" 。
  • url_escaping_charset:用来 URL 转义(比如${foo?url})的字符集, 来计算转义(%XX)的部分。通常包含 FreeMarker 的框架应该设置它,所以你不 应该在模板中来设置。(程序员可以阅读程序开发指南/其他/字符集问题部分来获 取更多内容)
  • classic_compatible:这是对专业人员来说的,它的值应该是一个布尔值。 参见 freemarker.template.Configurable 的文档来获取更多信息

function

语法:

<#function name param1 param1 ...paranN> ........ <#return returnValue> ......... </#function>

name:方法名称 param:参数 =xx 可以选项设置参数默认值,没有默认值参数必须再有默认值参数前面 parma支持动态参数...

创建一个i额方法变量

自定义标签(指令)

freemarker支持两种自定义标签方式:

  • 使用macro指令
  • 通过java 代码实现 freemarker.template.TemplateDirectiveModel类扩展

macro

语法:

<#macro tagName param1 param2=value2> .....宏定义体 [<#nested>] [<#return>] </#macro>

tagName:调用宏指令的时候必须用@代替#。e.g: <@tagName param="value"> parma1:参数名称,可以参数设置默认值:param=value.尽量放在参数最后。 调用宏指令时必须填写所有参数(除非参数有默认值) 宏定义体:是ftld莫板块,可以解析任何ftl指令函数。 nested: 嵌套内容。执行位于开始标签和结束标签之间模版代码。可以重复使用nested

nested

语法

<#nested [var1,var2]>

嵌套指令。执行位于开始标签和结束标签之间模版代码 var1,var2:处理循环变量使用。联合macro 定义循环变量

宏循环变量

语法:

<#macro tagName param > <#nested loopVar1,loopVar2> </#macro>

<@tagName param=value ;loopVar1,loopVar2> ${loopVar1},${loopVar2} /@tagName

注:使用时宏指令循环变量时注意和nested定义顺序一致。定义循环变量和nested指令定义处理循环变量如果参数个数不对称,则最后不对称参数不处理。详见官方

return

语法:

<#return [returnValue]>

returnValue: 计算值表达式 在function,macro指令中可以随处使用。直接返回,不处理后面内容

attempt, recover

语法:

<#attempt> ........... 执行ftl指令体 <#recover> 捕获异常体 ........... </#attempt>

类似于java中 try,catch。${.error}可以查看错误

更多标签内容详见官网

特殊变量

.variable_name

freemarker系统内部定义变量访问方式。 变量:

  • data_model: 访问数据模型的哈希表
  • error: 存储发生错误信息
  • globals: 访问全局变量的哈希表
  • locale:本地设置值
  • version:当前版本
  • now:当前时间

更多标签内容详见官网

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment