google closure 笔记-SOY template

一使用js模板

closure template 目前支持Java和js。但是模板语法的设计不依赖于任何现成的语言，所以理论上可以支持任何语言，只是暂时只有java编译器。

使用js模板：编写模板文件 .soy文件，然后用一个java编写的编译器将其编译为js文件，这个编译好的js文件会提供一个函数来输出模板内容，

只需要引入这个js文件然后在js中调用这个函数就可以得到模板的内容(内容是一个字符串)。

1, 下载工具包

http://closure-templates.googlecode.com/files/closure-templates-for-javascript-latest.zip

解压之后会得到两个文件：

SoyToJsSrcCompiler.jar， java编写的编译器，可以把soy模板编译为js文件

soyutils.js，编译器编译模板时需要使用的工具类。

2 模板语法

一个完整的模板hello.soy 源码如下

1 {namespace demo.hello}
2 /**
3 * Says hello to the world.
4 */
5 {template .helloWorld}
6 Hello world!
7 {/template}

第一行是声明命名空间

第二行是注释，注意，这个注释必须得加，不然编译器会报错

第5行是模板名，是相对于demo.hello命名空间的，即为demo.hello.helloWorld

第6行是输出的内容

第7行是闭合标签

3 编译模板

SoyToJsSrcCompiler.jar可以将soy文件编译为js文件，编译器的使用如下

java -jar ../SoyToJsSrcCompiler.jar --outputPathFormat hello.js hello.soy

编译好的js文件会生成一个全局变量： demo.hello.helloWorld 函数，这个函数返回一个字符串就是编译好的模板的内容。

使用此模板时只需要document.write(demo.hello.helloWorld())即可。

4 使用模板

新建一个hello.html，内容如下

1 <html>
2 <head>
3 <title>The Hello World of Closure Templates</title>
4 <script type="text/javascript" src="../soyutils.js"></script>
5 <script type="text/javascript" src="hello.js"></script>
6 </head>
7 <body>
8 <script type="text/javascript">
9 // Exercise the .helloWorld template
10 document.write(demo.hello.helloWorld());
11 </script>
12 </body>
13 </html>

其中：

第3,4行分别引入了工具类和编译好的模板文件，注意一定要先引入soyutils.js文件

第10行使用了模板hello.js提供的一个函数 demo.hello.helloWorld

5 添加另一个模板

在上述的hello.soy文件后追加如下代码

9 /**
10 * Greets a person using "Hello" by default.
11 * @param name The name of the person.
12 * @param? greetingWord Optional greeting word to use instead of "Hello".
13 */
14 {template .helloName}
15 {if not $greetingWord}
16 Hello {$name}!
17 {else}
18 {$greetingWord} {$name}!
19 {/if}
20 {/template}

这个新加的模板中使用了两个变量name和greetingWord。

编译此模板后生成的hello.js代码如下

1 // This file was automatically generated from hello.soy.
2 // Please don't edit this file by hand.
3
4 if (typeof demo == 'undefined') { var demo = {}; }
5 if (typeof demo.hello == 'undefined') { demo.hello = {}; }
6
7
8 demo.hello.helloWorld = function(opt_data, opt_sb) {
9 var output = opt_sb || new soy.StringBuilder();
10 output.append('Hello world!');
11 return opt_sb ? '' : output.toString();
12 };
13
14
15 demo.hello.helloName = function(opt_data, opt_sb) {
16 var output = opt_sb || new soy.StringBuilder();
17 output.append((! opt_data.greetingWord) ? 'Hello ' + soy.$$escapeHtml(opt_data.name) + '!' : soy.$$escapeHtml(opt_data.greetingWord) + ' ' + soy.$$escapeHtml(opt_data.name) + '!');
18 return opt_sb ? '' : output.toString();
19 };

可以看到其中生成了两个函数helloWorld和helloName

传递参数的方式很简单，只需要在调用的时候把参数以key-value的形式传入即可

1 <html>
2 <head>
3 <title>The Hello World of Closure Templates</title>
4 <script type="text/javascript" src="../soyutils.js"></script>
5 <script type="text/javascript" src="hello.js"></script>
6 </head>
7 <body>
8 <script type="text/javascript">
9 // Exercise the .helloWorld template
10 document.write(demo.hello.helloWorld());
11 document.write("<br />" + demo.hello.helloName({name:"bob"})); //传递参数
12 document.write("<br />" + demo.hello.helloName({greetingWord:"wellcome:" ,name:"Lily"})); //传递两个参数
13 </script>
14 </body>
15 </html>

二使用java模板

编写模板的规则都是一样的，依然按上面描述的方法来编写一个soy文件，不同之处是：

js模板需要用一个编译器编译为js文件，而java模板则直接在servlet中创建一个对象，这个对象可以将soy文件编译为字符串。

下载工具包：

http://closure-templates.googlecode.com/files/closure-templates-for-java-latest.zip

新建HelloWorld.java文件：

1 import com.google.template.soy.SoyFileSet;
2 import com.google.template.soy.data.SoyListData;
3 import com.google.template.soy.data.SoyMapData;
4 import com.google.template.soy.tofu.SoyTofu;
5
6 import java.io.File;
7
8 public class HelloWorld {
9
10 public static void main (String[] args) {
11
12 // Bundle the Soy files for your project into a SoyFileSet.
13 SoyFileSet sfs = new SoyFileSet.Builder().add(new File("demo/hello.soy")).build();
14
15 // Compile the template into a SoyTofu object.
16 // SoyTofu's newRenderer method returns an object that can render any template in file set.
17 SoyTofu tofu = sfs.compileToJavaObj();
18
19 // Call the template with no data.
20 System.out.println(tofu.newRenderer("demo.hello.helloWorld").render());
21 System.out.println(tofu.newRenderer("demo.hello.helloName")
22 .setData(new SoyMapData(
23 "name", "Ana",
24 "additionalNames")
25 ).render());
26 }
27 }

然后编译运行代码：

javac -classpath soy-latest.jar HelloWorld.java

java -classpath soy-latest.jar HelloWorld

结果总是出错，不知道为什么⋯⋯

三模板语法

语句：

模板中语句分为两类，html语句和模板语句，所有的模板语句都包括在{}中。一般语法如下：

{command value}

如果省略command，则默认为print

变量：

变量以$符号开头：

{$name}

引用类型的数据，其输出方式类似于js，

$a.0.c == $a[0].c == $a[0]["c"]

因为模板会自动删除多余空格，所以可以用{sp}或者{nil}来添加空格

在namespace声明中可以指定escape

{namespace ns autoescape="contextual"}

模板支持的变量类型如下

Type	Literal
Null	null
Boolean	false or true
Integer	Decimal (e.g. -827) or hexadecimal (must begin with 0x and must use capital A-F, e.g. 0x1A2B).
Float	Must be in decimal and must either: Have digits both before and after the decimal point (both can be a single 0), e.g. 0.5, -100.0, or Have a lower-case e that represents scientific notation, e.g. -3e-3, 6.02e23. Note: Even though the primitive type is named Float, it has the precision of a number in JavaScript or a double in Java.
String	Delimited by single quotes only. Closure Templates support these escape sequences: \\, \', \", \n, \r, \t, \b, \f, and \u#### where the #### can be any 4 hex digits to denote a Unicode code point.
List	A comma-separated list of heterogeneous values, for example: [1, 'two', [3, 'four']]. [] is the empty list.
Map	['key': 'value', <keyExpr>: <valueExpr>] maps keys to values. Square brackets ([…]) delimit both lists and maps because braces ({…}) delimit commands. [:] is the empty map.

运算符

- (unary) not
* / %
+ - (binary)
< ]]]]> <= >=
== !=
and
or
?: (ternary)

函数：

模板提供的基本函数如下：

Function	Usage
isFirst($var)	Use this with the foreach command. For more information see the foreach section of the Commands chapter.
isLast($var)	Use this with the foreach command. See more information in the foreach section of the Commands chapter.
index($var)	Use this with the foreach command. See more information in the foreach section of the Commands chapter.
hasData()	Checks whether a template data object was passed to this template. This function is rarely needed — use it only if all parameters to a template are optional, and thus the template may be called without any data object at all (omitted or null in javascript or null in Java). In this situation, the correct way to check for the presence of a parameter is {if hasData() and $myParam}. Alternatively, if you choose to always pass an empty data map (i.e. never pass null) to your template even when none of the optional params are needed, then you never have to use the hasData() function.
length($list)	The length of a list.
keys($map)	The keys in a map as a list. There is no guarantee on order.
round(number)	Round to an integer.
round(number, numDigitsAfterDecimalPoint)	If numDigitsAfterDecimalPoint is positive, round to that number of decimal places; if numDigitsAfterDecimalPoint is negative, round to an integer with that many 0s at the end.
floor(number)	The floor of the number.
ceiling(number)	The ceiling of the number.
min(number, number)	The min of the two numbers.
max(number, number)	The max of the two numbers.
randomInt(rangeArg)	A random integer in the range [0, rangeArg - 1] (where rangeArg must be a positive integer).

注释：

// begins a rest-of-line comment
/* comment */ delimit an arbitrary comment (can be multiline)

详细语法：见：https://developers.google.com/closure/templates/docs/commands