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 源碼如下
[javascript] view plain copy
- 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，內容如下
[javascript] view plain copy
- 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文件後追加如下代碼
[javascript] view plain copy
- 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代碼如下
[javascript] view plain copy
- 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的形式傳入即可
[javascript] view plain copy
- 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文件：
[java] view plain copy
- 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:
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. |
運算符
- - (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
google closure 筆記-SOY template