google clourse template 学习笔记

google clourse template:

这个模板主要是为了在java或javascript中方便的生成创建动态html的代码,主要分两部分javascript版本和java版本,它们需要不同的jar包和不同的js库,它们运用的方式也有较大的差别.

一.javascript部分:
  主要包括2个核心文件
SoyToJsSrcCompiler.jar 一个独立的可执行的jar文件,它负责将模板源文件(soy文件)编译成有效的javascript函数
soyutils.js 一个独立的js库,所有的通过编译模板源文件得到的javascript代码都需要它才能正常运行.
   SoyToJsSrcCompiler.jar编译soy文件生成js函数,借助soyutils.js的支持,生成的js函数可以动态生成html.这里核心的部分是soy文件的编写,在后面集中进行讲解.
SoyToJsSrcCompiler.jar的运行方法:
  java -jar SoyToJsSrcCompiler.jar  --outputPathFormat 生成的js文件路径   soy文件路径

二.java部分
   1.主要包括2个文件:
    soy.jar 一个独立的jar文件,包含了所有的模板类以及它们的依赖.通过它提供的接口我们可以编写代码根据soy文件生成需要的html.这跟javascript部分不同,javascrit部分是生成能够生成html的js函数,js函数一旦生成,则不再依赖soy文件.而java部分则是直接通过提供的接口编写java方法用于根据(解析)soy文件生成html,它是依赖soy文件的.
    SoyParseInfoGenerator.jar 是一个可执行的jar文件,它能分析soy文件产生包含模板和参数信息的java类(soyFileInfo类).主要作用是方便保持soy文件中参数名,方法名与java类的相应名字的对应关系,soy文件中参数名或方法名修改之后只要通过SoyParseInfoGenerator.jar重新生成一此soyFileInfo就行,无需在其他地方做对应的修改(这些修改可能会导致遗漏)
   2.几个重要的类:
看一个例子
import com.google.template.soy.SoyFileSet;
import com.google.template.soy.data.SoyMapData;
import com.google.template.soy.tofu.SoyTofu;

import java.io.File;

public class HelloWorld {

  public static void main (String[] args) {

// 以SoyFileSet的形式绑定一个或多个soy文件到你的工程.add方法可以连写以绑定多个soy文件(new SoyFileSet.Builder()).add(new File("simple.soy")).add(new File(path)).build();
    SoyFileSet sfs = (new SoyFileSet.Builder()).add(new File("simple.soy")).build();

     //将模板编译成SoyTofu对象
    //SoyTofu 有一个render方法,它能将SoyFileSet中所有的模板翻译html
    SoyTofu tofu = sfs.compileToJavaObj();

    /** render方法有3个参数,第一个参数对应soy文件中的命名空间,第2个参数是需要提供的参数,需要封装成SoyMapData,第三个参数是SoyMsgBundle主要用于多语言的翻译(这个后面专门讲解),
     *     如果无需多语言支持则为null即可.
    *   SoyMapData 中存放的是参数名,值对,可以象一个java map那样创建 SoyMapData aMap = new SoyMapData();aMap.put("xx","xx"),也可以这样 new SoyMapData(名,值,名,值...)
     */
    System.out.println(tofu.render("examples.simple.helloWorld", (SoyMapData) null, null));
  }

}
  上面通过一个简单的例子简单分析了以下及个类
   SoyFileSet : 用来绑定soy文件
   SoyTofu : 将模板编译成SoyTofu对象
   SoyMapData : 存放参数名,值对.名和值都可以是任意的SoyData类型(不能是普通java对象,否则会抛出一个未绑定的对象的异常),SoyData包括基本数据类型,字符串,SoyListData等
    通过这些我我们已经可以进行简单的基本的应用了.
3.SoyParseInfoGenerator.jar的应用
java -jar SoyParseInfoGenerator.jar --outputDirectory generated --javaPackage generated --javaClassNameSource filename simple.soy
这个命名表示创建一个generated文件夹 ,并在generated文件夹下生成一个名为simpleSoyInfo.java的文件,这个文件中包含与soy文件中变量,模板字符串相当的常量.

三 翻译
1.首先下载SoyMsgExtractor.jar 此jar包可以将soy文件格式化成xlf文件
命令为 : java -jar SoyMsgExtractor.jar  --outputFile extracted_msgs.xlf  aaa.soy bbb.soy
注:XLIFF 是用来在参与翻译项目的各方之间交换本地化数据的格式。这种特殊的格式使翻译人员能够把精力集中到所翻译的文本上，而不用担心文本的布局。
  XLIFF 标准得到了大量本地化服务提供商和本地化工具提供商的支持。
           翻译文档时使用 XLIFF 最主要的原因是，在翻译不同类型的文档时，您可以使用单一的文件格式
得到不同语言的xlf文件之后
   对于java :使用SoyMsgBundle进行翻译处理,具体如下
SoyMsgBundleHandler msgBundleHandler = new SoyMsgBundleHandler(new XliffMsgPlugin());
SoyMsgBundle msgBundle = msgBundleHandler.createFromFile(new File("translated_msgs_pt-BR.xlf"));
将创建的msgBundle传给SoyToFun的render方法,这样产生的html时soy文件中msg标签对应的文本就显示的语言就是xlf文件的语言.
   对于javascript :
java -jar SoyToJsSrcCompiler.jar  --locales en,de,pt-BR  --messageFilePathFormat translated_msgs_{LOCALE}.xlf \
        --outputPathFormat '{INPUT_FILE_NAME_NO_EXT}_{LOCALE}.js'  aaa.soy bbb.soy

四 soy文件的编写
    soy文件是整个模板的核心,它有自己的语法,能够定义参数,有分支,循环等结构,可以说是一个简单的语言,soy文件的语法跟大多数编程语言的语法类似,比较容易学.
   1.soy文件的特殊字符
Special Character  Equivalent Raw Text
{sp}                         空格
{nil} 空串
{\r} 回车
{\n} 换行
{\t} 制表符
{lb} 左大括号"{"
{rb} 右大括号"}"
   2.soy文件标签
1)soy文件头必须以一个命名空间的定义开始{namespace xx.xxx} 它表示该soy文件下所有的模板都是在该namespace下

2) template /template 表示一个模板,用法如下:其中template_name必须以"."开头,表示模板的名字,"{"必须定格写
  {template <template_name>}
  ...
  {/template}
      3) literal, /literal 这个跟xml的<![CDATA[...]]>类似,其中可以直接写特殊字符 比如空格,大括号等无需特殊表示

      4) {<expression>}
{print <expression>} 输出<expression> print可省略
      5) msg, /msg 定义需要翻译的消息 语法:
{msg desc="<help_text_for_translators>"}
  ...
{/msg}

6) if, elseif, else, /if 分支标签,语法:
{if <expression>}
  ...
{elseif <expression>}
  ...
{else}
  ...
{/if}
7) switch, case, default, /switch 分支标签 语法:
{switch <expression>}
  {case <expression_list>}
    ...
  {case <expression_list>}
    ...
  {default}
    ...
{/switch}
8) foreach, ifempty, /foreach  迭代标签 语法:
{foreach <local_var> in <data_ref>}
  ...
{ifempty}
  ...
{/foreach}
{foreach <local_var in <data_ref>}比较好理解就是一遍历,{ifempty} 表示<data_ref>为空时执行的语句
另外在foreach语句中还有几个标签可以用 分别是 :    isFirst($var)  isLast($var) index($var)
9) for, /for  循环标签 语法:
{for <local_var> in range(<expression1>, <expression2>, <expression3>)}
  ...
{/for}
这里主要讲解一下rang的含义,rang将返回一个从起始值到最大值间隔为<expression3>的数组,它的参数个数可以是3个,2个或1个.
3个参数时分别表示,起始值,最大值,步长.2个数参数时则步长默认为1,1个参数时起始值得默认为0
10) call, /call, param, /param 调用其他模板的结果,相当于函数调用,语法:
{call <template_name> data="<data_to_pass>" /}
或
{call <template_name> data="<data_to_pass>"}
  {param <key1>: <expression> /}
  {param <key2>}
    ...
  {/param}
{/call}
<template_name>表示调用的模板的名字,data传给待调用模板的参数,param用来设置待调函数的相应的参数值.
data="all"表示用当前模板的参数传给调用模板,前提是调用模板的参数是当前模板参数的子集,名字必须全部匹配.
   3.soy文件必须以一个新的空行结尾 就是文件结束后得多出一行,否则就会出错.

docs详见:http://code.google.com/intl/zh-CN/closure/templates/docs/overview.html
javascript版本下载 :http://code.google.com/intl/zh-CN/closure/templates/docs/helloworld_js.html
java版本下载 : http://code.google.com/intl/zh-CN/closure/templates/docs/helloworld_java.html
翻译需要的xlf格式化工具下载 : http://code.google.com/intl/zh-CN/closure/templates/docs/translation.html