BlogJava-俺们那嘎达-文章分类-FreeMarkerhttp://www.blogjava.net/livery/category/23345.html找到属于自己的一片天空zh-cnFri, 22 Jun 2007 15:42:36 GMTFri, 22 Jun 2007 15:42:36 GMT60webwork中的FreeMarkerhttp://www.blogjava.net/livery/articles/125562.html心情经纬心情经纬Thu, 21 Jun 2007 06:21:00 GMThttp://www.blogjava.net/livery/articles/125562.htmlhttp://www.blogjava.net/livery/comments/125562.htmlhttp://www.blogjava.net/livery/articles/125562.html#Feedback0http://www.blogjava.net/livery/comments/commentRss/125562.htmlhttp://www.blogjava.net/livery/services/trackbacks/125562.htmlFreeMarker是一个Java模版语言，它是 JSP 的绝佳替代方案. FreeMarker在你的action result可能需要在Servlet容器环境以外被载入的情况下是理想选择. 例如,如果你希望在你的应用程序中支持plugins,你可能会乐意使用Freemarker，因为那样的话plugins可以支持将所有的action class和view都打包到一个从classloader进行装载的jar文件里面.
关于FreeMarker的更多信息，请访问FreeMarker网站.

FreeMarker与Velocity非常相似, 它们都是可以在Servlet容器外使用的模版语言. WebWork小组更推荐FreeMarker, 而不是Velocity, 这是因为FreeMarker提供了更好的错误报告, 支持JSP标签, 稍多的功能. 当然, 这两种技术都是代替JSP的很好方案.

快速上手

确认配置好你的项目的classpath中的所有依赖以后, 开始使用FreeMarker就非常简单了. 典型情况下只需要 freemarker.jar. 除它以外, webwork-default.xml已经配置好了将FreeMarker Result映射到你的模版文件. 你现在可以试验一下如下 xwork.xml 配置:

<action name="test" class="com.acme.TestAction">
<result name="success" type="freemarker">test-success.ftl</result>
</action

然后写好 test-success.ftl:

<html>
<head>
<title>Hello</title>
</head>
<body>
Hello, ${name}
</body>
</html>

这里 name 是你的action中的一个属性. 这样就可以了! 该文档的余下部分将介绍模版如何被加载, 变量如何解析, tags(标签)也可以使用.

模版加载

Webwork在两个位置查找FreeMarker模版(按顺序):

  1. Web应用程序目录(Web application)
  2. Class path
    这个顺序对于在完全编译的jar中提供模版很理想, 但是也同时支持在Web应用程序目录中定义这些模版来覆盖jar中的模版文件. 事实上, 这就是为什么你可以覆盖WebWork中默认的UI tags和Form Tags的原理.
    还有, 你可以通过templatePath 上下文变量(context variable)指定一个路径(你的文件系统中的一个目录). 如果指定了该变量, 那么这个目录中的内容将会被优先寻找.

变量解析/决定(Resolution)

在FreeMarker中, 变量将会在多个位置进行寻找, 顺序如下:

  1. 值栈(value stack)
  2. action上下文(action context)
  3. Request范围(scope)
  4. Session范围(scope)
  5. Application范围(scope)
  6. 内建变量
    注意action上下文在value stack后进行搜索. 这意味着你可以引用变量而不必使用标准的符号(#)前缀，不像在JSP中使用ww:property中必须使用的那种语法(译者注:现在在JSP中也可以不用#而访问默认的ValueStack). 这是一个很好的便利特性, 但是小心, 它有时也会把你陷进去. 
    <@ww.url id="url" value="http://www.yahoo.com"/>
    Click <a xhref="${url}">here</a>!

Webwork-FreeMarker整合提供的内建变量如下:

Name Description
stack 值栈本身, 方便使用 ${stack.findString('ognl expr')}的方式调用
action 最近执行的action
response HttpServletResponse
res 与response相同
request HttpServletRequest
req 与reqeust相同
session HttpSession
application ServletContext
base request的上下文路径(context path)

标签支持

FreeMarker是很棒的模版语言, 因为它完整的支持标签(tag). 参照WebWork提供的 FreeMarker Tags 文档中的如何使用通用(generic) Tags 部分获取更多信息. 除了那些, 你还可以使用任何的JSP标签(tag), 就像这样:

<#assign mytag=JspTaglibs["/WEB-INF/mytag.tld"]>
<@mytag.tagx attribute1="some ${value}"/>

这里 mytag.tld 是你使用的JSP标签库的定义文件. 注意: 为了使用FreeMarker的这个支持, 你必须开启 web.xml 2.1.x compatibility 文档中的 JSPSupportServlet.

提示和技巧

下面是在使用FreeMarker构建WebWork应用程序时的一些有用的进阶功能.

类型转换与本地化

FreeMarker内置支持日期与数字的格式化. 格式化的规则基于action request的地区信息(locale), locale是通过webwork.properties配置的, 它也可以通过I18n Interceptor进行覆盖. 这种方式一般会完美的满足你的需求, 但是你要记住, 这些格式化信息是通过FreeMarker处理的,而不是通过WebWork的类型转换支持实现.
如果你希望WebWork根据你所指定的类型转换处理格式化, 你不应该使用平常的&{...}语法. 取而代之, 你应该使用property标签. 区别在于property标签特别为OGNL表达式设计， 计算它的值， 然后将结果用你指定的Type Conversion转换为String. 平常使用的${...}语法则会使用FreeMarker的表达式语言(EL), 计算它的值, 然后通过内建的格式化规则转化为String. 这些区别甚微, 但是一定要了解.

扩展

有时你可能需要扩展WebWork提供的FreeMarker支持. 最常见的原因是你希望引入你自己的标签, 就像你扩展WebWork内建标签一样.
如果需扩展, 首先要新建一个继承 com.opensymphony.webwork.views.freemarker.FreemarkerManager 并且重载了相应方法的类. 然后将下面代码添加到webwork.properties:

webwork.freemarker.manager.classname = com.yourcompany.YourFreeMarkerManager

ObjectWrapper设置

如果你熟悉了FreeMarker, 你会发现它的敏感性会带来一些困扰. 最常见的方法就是尝试使用FreeMarker提供的BeanWrapper. 如果你不知道那是什么,别担心. 只要知道这些酒可以了:

WebWorkBeanWrapper继承自默认的FreeMarker BeansWrapper, 提供了基本完全一致的功能, 只是修改了maps处理机制. 一般, FreeMarker有两种操作模式: 一种支持友好的内置的map (?key, ?values, etc),但是只支持String作为key; 或者特殊的内置支持(例如: ?key 返回map的相应方法而不是key), 但是它支持String和String相似的非String作为key. WebWork提供了两种情况下的可选的实现方案.
这种特殊的做法也许会让你迷惑或产生问题. 所以, 你可以将 webwork.properties 中的*webwork.freemarker.wrapper.altMap*设置为false, 允许替换为常规的BeansWrapper逻辑.

语法注释

如果是FreeMarker 2.3.4, 还支持另外的语法. 这种可选的语法在你感觉你使用的IDE(尤其是ItelliJ IDEA)在默认的语法下运行困难时非常有用. 关于这种语法的更多内容, 请阅读这里



心情经纬 2007-06-21 14:21 发表评论
]]>FreeMarker学习1(Ftl)http://www.blogjava.net/livery/articles/124263.html心情经纬心情经纬Thu, 14 Jun 2007 03:50:00 GMThttp://www.blogjava.net/livery/articles/124263.htmlhttp://www.blogjava.net/livery/comments/124263.htmlhttp://www.blogjava.net/livery/articles/124263.html#Feedback0http://www.blogjava.net/livery/comments/commentRss/124263.htmlhttp://www.blogjava.net/livery/services/trackbacks/124263.html<# ... > 中存放所有freemaker的内容，之外的内容全部原样输出。
<@ ... /> 是函数调用
两个定界符内的内容中，第一个符号表示指令或者函数名，其后的跟随参数。freemaker提供的控制包括如下：
<#if condition><#elseif condition><#else></#if> 条件判断
<#list hash_or_seq as var></#list> 遍历hash表或者collection（freemaker称作sequence）的成员
<#macro name param1 param2 ... ><#nested param></#macro> 宏，无返回参数
<#function name param1 param2><#return val></#function>函数，有返回参数
var?member_function(...) 用函数对var进行转换，freemaker称为build-ins。实际内部实现类似member_function(var, ...)
stringA[M .. N] 取子字符串，类似substring(stringA, M, N)
{key:value, key2:value2 ...} 直接定义一个hash表
[item0, item1, item2 ...] 直接定义一个序列
hash0[key0] 存取hash表中key对应的元素
seq0[5] 存取序列指定下标的元素
<@function1 param0 param1 ... /> 调用函数function1
<@macro0 param0 param1 ; nest_param0 nest_param1 ...> nest_body < /@macro > 调用宏，并处理宏的嵌套
<#assign var = value > 定义变量并初始化
<#local var = value> 在 macro 或者 function 中定义局部变量并初始化
<#global var = value > 定义全局变量并初始化
${var} 输出并替换为表达式的值
<#visit xmlnode> 调用macro匹配xmlnode本身及其子节点
<#recurse xmlnode> 调用macro匹配xmlnode的子节点
<#if condition > </#if>
<#list SequenceVar as variable > repeatThis </#list>
<#include "/copyright_footer.html">

一个ftl标记不能放在另外一个ftl标记里面，但是注释标记能够放在ftl标记里面。

系统预定义指令采用<#...></#>
用户自定义指令采用<@...></@>

hash片段可以采用： products[10..19] or products[5..] 的格式。

序列也可以做加法计算：passwords + {"joe":"secret42"}

缺省值: name!"unknown" 或者 (user.name)!"unknown" 或者 name! 或者 (user.name)!

null值检查: name?? or (user.name)??

转义列表：

Escape sequence

Meaning

\"

Quotation mark (u0022)

\'

Apostrophe (a.k.a. apostrophe-quote) (u0027)

\\

Back slash (u005C)

\n

Line feed (u000A)

\r

Carriage return (u000D)

\t

Horizontal tabulation (a.k.a. tab) (u0009)

\b

Backspace (u0008)

\f

Form feed (u000C)

\l

Less-than sign: <

\g

Greater-than sign: >

\a

Ampersand: &

\{

Curly bracket: {

\xCode

Character given with its hexadecimal Unicode code (UCS code)

如果想打印${，则需要将{转义，可以写成"$\{user}"，或者可以用生字符（r指令）：$(r "${xx}"}

序列构成：<#list ["winter", "spring", "summer", "autumn"] as x>${x}</#list>

不同的对象可以存放在一个序列里面，比如：[2 + 2, [1, 2, 3, 4], "whatnot"]. 第一个是数字，第二个是序列，第三个是字符串。

可用采用start..end的方式来定义一个数字序列，start可以小于end，同时，end也可以省略。

hash取值支持一下四种模式：book.author.name, book["author"].name, book.author.["name"], book["author"]["name"].

特殊变量是指freemaker引擎本身定义的变量。访问时，以.variable_name的语法访问。

变量表达式支持嵌套模式，比如：${"Hello ${user}!"}。

变量表达式在指令中的使用情况：
变量表达式可以在指令中，用“”的方式存在，不如：<#include "/footer/${company}.html">.
但是不允许下面的方式存在： <#if ${isBig}>Wow!</#if>, 正确写法是：<#if isBig>Wow!</#if>.
而且 <#if "${isBig}">Wow!</#if>写法也不正确，因为"${isBig}"返回的是字符串，不是boolean类型。

字符串中取字符或字符串采用以下语法：${user[0]},${user[0..2]} ${user[4..]},${user?string(4)}

序列操作：
   加法：<#list ["Joe", "Fred"] + ["Julia", "Kate"] as user> 但要注意串联之后的读取速度变慢。
   子序列：seq[1..4]

序列和hash的串联都只能用于两个相加，不能有多个相加的模式，hash相加，如果两个相加的hash存在相同的key，则后面会覆盖前面的。

在使用>=或者>时，需要注意一些问题，因为freemaker会将>解释成标记的关闭符，为了解决这个问题，需要在表达式加上括号，比如： <#if (x > y)>. 或者使用 &gt; and &lt符号来代替。

无值变量（包括无该变量，null，返回void，无属性等）：unsafe_expr!default_expr or unsafe_expr! or (unsafe_expr)!default_expr or (unsafe_expr)!
缺省值可以是任何类型，不一定是数字，比如：hits!0 或者 colors!["red", "green", "blue"].

如果缺省值忽略，那么将会默认为空串、空序列或者空hash，因为freemarker支持多类型的值。不过要让默认值为0或false，则不能省略缺省值。

非顶层变量的无值处理：
   product.color!"red"：只处理product不为空，color为空的缺省值处理，如果product为空，则freemaker会抛出异常。(product.color)!"red"：则会处理product为空，color为空，或者没有color属性的无值情况。

无值变量的判断操作：unsafe_expr?? or (unsafe_expr)??

判断变量是否是无值。

普通变量插入方式: ${expression},${3+5);
数字变量插入方式: #{expression} or #{expression; format}：过期。
变量只能用于文本区或者是字符串里面，比如：<h1>Hello ${name}!</h1>以及 <#include "/footer/${company}.html">

数字值的插入：根据缺省的number_format输出，以及可以通过setting来达到设置数字格式的目的，也可以通过内置函数string来改变输出格式。

日期类型的格式设置：date_format, time_format 和 datetime_format


定义宏：
   不带参数：<#macro 宏名>...</#macro>，引用<@宏名 />
   带参数：<#macro 宏名 参数...>...</#macro>，引用<@宏名 参数1=值1.../>，带有参数的宏，调用是参数的值必须和参数的个数相同。当然也可以在宏定义时给参数一些默认值。比如：<#macro greet person color="black">


宏里面的嵌套内容：
<#macro border>
  <table border=4 cellspacing=0 cellpadding=4><tr><td>
    <#nested>
  </tr></td></table>
</#macro> 
在宏的定义body中加入<#nested>指令。嵌套的内容可以是任何正确的ftl块。

宏的本地变量在嵌套内容中是不可见的。

宏定义时，<#nest>指令相当于调用定义的内容，而使用宏时，nest body相当于定义。
 
<#macro repeat count>
<#list 1..count as x>
<#nested x, x/2, x==count>
</#list>
</#macro>
<@repeat count=4 ; c, halfc, last>
${c}. ${halfc}<#if last> Last!</#if>
</@repeat> 


定义变量：
   在模板中定义的变量将会隐藏（不是更改）数据模型根下面的同名的变量。

模板中的3种类型变量：
   1：plain variables，能够在模板中的任何地方访问，一个模板include另外一个模板，也可以访问被包含模板的变量。可以通过assign或者macro指令产生或替换变量。
   如果要访问数据模型中的变量，则可以通过.global来访问：
   <#assign user = "Joe Hider">
   ${user}          <#-- prints: Joe Hider -->
   ${.globals.user} <#-- prints: Big Joe--> 
   2：Local variables，宏定义body中用local指令创建或者替换。
   3：Loop variables:由list指令产生。


namespaces:
<#import "/lib/my_test.ftl" as my> <#-- the hash called "my" will be the "gate" -->
<@my.copyright date="1999-2002"/>
${my.mail} 

设置命名空间里面的变量：<#assign mail="jsmith@other.com" in my>

命名空间与数据模型：命名空间的ftl可以访问数据模型的变量。同样命名空间的变量也会隐藏数据模型中同名的变量。

空白问题：
1：White-space stripping，默认为enabled，清除ftl标记带来的空白以及缩进。处理模板的空白。
2：t, rt, lt指令。
3：ftl的参数strip_text.

用compress directive或者transform来处理输出。
<#compress>...</#compress>：消除空白行。
<@compress single_line=true>.../@compress将输出压缩为一行。

可替换语法：
freemarker可用"["代替"<".在模板的文件开头加上[#ftl].

心情经纬 2007-06-14 11:50 发表评论
]]>