How to migrate jetbrick-template from 1.x to 2.x

jetbrick-template-migrate.md

1. 语法方面 ===================

• 不再支持的语法

  • 泛型定义: #define(List<String> str)
  • 强制类型转换: (String) s
  • ?. / ?[ NULL 安全调用: a?.b
  • ++ / --: i++
  • #put(key, value)

• 语法变更

  • 关于 #define

    默认情况下 syntax.strict = false, 变量不再需要进行 #define 类型声明

  • 静态方法/字段调用

    1.x 语法	2.x 语法
    @Integer.MAX_VALUE	Integer::MAX_VALUE
    @(java.lang.Integer).MAX_VALUE	java.lang.Integer::MAX_VALUE
    @(java.lang.Integer).valueOf(..)	java.lang.Integer::valueOf(..)

• 新增语法

  • #options 选项指令

    #options (
      loadmacro = "/macors/commons.jetx",
      loadmacro = "/macors/users.jetx",
      import = "java.lang.*",
      import = "java.util.*",
      strict = true,
      safecall = true,
      trimLeadingWhitespaces = true
    )
    

    其中：

    • strict = true 代表模板中用到的变量必须先进行 #define, 否则出错
    • safecall = true 开启安全调用
    • import 引入 package
    • loadmacro 引入外部文件中的 macro 定义
    • trimLeadingWhitespaces 删除文件头上的空白内容

  • 增加 ===, !== 直接内存地址比较

  • 支持 enum 对象，语法和静态字段访问相同, java.nio.file.AccessMode::READ

  • 支持 Integer::class 等价于 Integer.class，原来就支持 object.class 等价于 object.getClass()

  • 增加 a ?: b 简化版的三元表达式，等价于 a != null ? a : b

  • 增强 Map 常量， { name: "jetbrick", ... } 上面的 key 允许不加 单/双引号，和 JS/JSON 保持一致

  • #call macro_name(...)

    用来调用 macro，

  • #return ( obj )

    用来返回子模板变量，这样父模板就可以使用子模板返回的数据

2. 配置方面 ===================

1.x 名称	2.x 名称	其他说明
import.packages	jetx.import.classes	不在支持 com.pkg, 后面必须加 com.pkg.*
import.classes	jetx.import.classes
import.variables	jetx.import.defines	变更
global.variables
import.methods	jetx.import.methods
import.functions	jetx.import.functions
import.tags	jetx.import.tags

                            | jetx.import.macros         | 导入全局 macro

import.autoscan | | 自动(无需配置) import.autoscan.packages | jetx.autoscan.packages | 变更
| jetx.autoscan.skiperrors | 遇到错误跳过 input.encoding | jetx.input.encoding |
output.encoding | jetx.output.encoding |
| jetx.syntax.strict | 严格语法模式，默认false
syntax.safecall | jetx.syntax.safecall |
template.loaders | jetx.template.loader | 默认改为 jetbrick.template.loader.ClasspathResourceLoader template.path | | 由每个 loader 自己配置
template.reloadable | | 由每个 loader 自己配置
template.suffix | jetx.template.suffix |
compile.tool | |
compile.strategy | |
compile.debug | |
compile.path | |
security.manager | | 暂未实现
security.manager.file | |
security.manager.namelist | |
| jetx.trim.leading.whitespaces | 删除文件头上的空白内容 trim.directive.line | jetx.trim.directive.whitespaces | 变更 trim.directive.comments | jetx.trim.directive.comments |
trim.directive.comments.prefix | jetx.trim.directive.comments.prefix |
trim.directive.comments.suffix | jetx.trim.directive.comments.suffix |

默认直接支持多 path 的 loader

template.loaders = $path1, $path2, $path3

$path1 = jetbrick.template.loader.ClasspathResourceLoader
$path1.root = /template1

$path2 = jetbrick.template.loader.ClasspathResourceLoader
$path2.root = /template2

$path3 = jetbrick.template.loader.FileSystemResourceLoader
$path3.root = /tmp/template2
$path3.reloadable = true

3. API 相关 ===================

• 扩展函数/扩展方法

  对于使用上下文相关的扩展，第一个参数为 JetPageContext，现在不在支持。 要获取相关的上下文参数，改为如下方式获取：

  public static User getSessionUser() {
    InterpretContext ctx = InterpretContext.current();
    HttpSession session = ctx.getValueStack().getValue(JetWebContext.SESSION);
    return session.getAttribute("user");
  }

• 移除 Web mvc 集成相关内容，改由扩展模块支持

  • jetbrick-template-servlet
  • jetbrick-template-jetbrickmvc
  • jetbrick-template-springmvc
  • jetbrick-template-jfinal
  • jetbrick-template-jodd
  • jetbrick-template-struts
  • jetbrick-template-nutz
  • jetbrick-template-servlet

• 内置全局变量

  • servletContext -> application
  • servletContextScope -> applicationScope

• 内置扩展方法/函数

  。。。

• 允许运行期进行动态配置 import class, function, method, tag, macro ...

• 运行期出错，提供详细的信息

jetbrick.template.TemplateException: NullPoinerException: object is null

Template: /template/test.jetx: 1,4
-------------------------------------------------------------------------------
   1: ${user.name}
            ^ -- here
-------------------------------------------------------------------------------

4. 关于父子模板的传递 =========================

• 2.x 不再支持 #put， 改用 #return 来返回变量

  儿子：

  #return( {p1: 123, p2: false} )
  

  老子：

  #include("child.jetx", {},  "obj")
  P1 from sub: ${obj.p1}
  P2 from sub: ${obj.p2}
  

• 2.x layout 方式变更

  layout 页面:

  header ...
  
  ==== block a:
  #tag layout_block_default('a')
    default a ....
  #end
  
  ==== block b: 
  #tag layout_block_default('b')
    default b ....
  #end
  
  ${c}
  
  footer ...
  

  详细页面：

  #tag layout_block('a')
    new block a
  #end
  
  #include('/layout.jetx', {c:'ccc'})
  

  结果:

  header ...
  
  ==== block a:
    new block a
  
  ==== block b:
    default block b
  
  ccc
  
  footer ...