Velocity.js —— 來自淘寶的 JS 模板引擎

注意

velocityjs在npm中包名從原來的velocity.js改為velocityjs，感覺require("velocity.js") 比較不好看，所以改名，從0.3.0之後的版本都在velocityjs下更新。

查看最新版本

 

  
$ npm info velocityjs version 
 

Velocity.js 是velocity模板文法的javascript實現。Velocity 是基於Java的模板引擎，廣泛應用在阿里集 體各個子公司。Velocity模板適用於大量模板使用的情境，支援複雜的邏輯運算，包含 基礎資料型別 (Elementary Data Type)、變數賦值和函數等功能。Velocity.js 支援 Node.js 和瀏覽器環境。

最新版：https://github.com/shepherdwind/velocity.js/zipball/master

Features

• 支援用戶端和伺服器端使用

• 文法是富邏輯的，構成門微型的語言

• 文法分析和模板渲染分離

• 基本完全支援velocity文法

• 瀏覽器使用支援模板之間相互引用，依據kissy模組載入機制

• 三個Helper，友好的資料類比解決方案

• Vim Syntax

Install

via npm:

 

 

  
$ npm install velocityjs 
 

Broswer Support

相容ie6+，chrome等其他瀏覽器，test case

點擊此處可以體驗web 端velocity文法解析過程，註：使用ACE作為代碼編輯器，僅支援進階瀏覽器訪問。

執行cake命令進行打包velocity.js瀏覽器端指令碼:

 

 

  
$ make parse  
 

需要cli下安裝coffeejs，暫時打包是為kissy所使用的，velocity.js需要的一些常用的 ecma5功能，比如foreach, some, isArray等，在node環境下是內建的功能，而web端的兼 容是交給已有的類庫解決。需要自行提供一組跨瀏覽器的api，比如kissy打包：

 

 

  
//api map  
  
var utils = {  
  
  forEach : S.each,  
  
  some    : S.some,  
  
  mixin   : S.mix,  
  
  guid    : S.guid,  
  
  isArray : S.isArray,  
  
  indexOf : S.indexOf,  
  
  keys    : S.keys,  
  
  now     : S.now  
  
};  
 

Velocity文法具有很高的容錯能力，類似於html結構的解析，同時文法規則複雜，所以文法 解譯器執行效能可能比較慢，velocity.js把文法結構分析運算和文法執行兩個過程獨立出來， 第一步，文法結構分析返回一個數組(文法樹)，描述velocity文法，文法執行使用資料和語 法樹，計算模板最終結果。

執行build後，得到兩個檔案，分別是build/velocity/下的index.js和parse.js，兩者 相互獨立，parse.js文法分析過程可以放在本地完成，執行命令：

把文法分析和模板拼接分開，為了方便在本地編譯文法樹，減少在web端js運算。本地編譯 模板的思路，源自KISSY的xtemplate。

雖然文法解譯器可以在瀏覽器端執行，但是，不推薦那麼使用。

 

 

  
#使用velocity命令列工具打包  
  
veloctiy --build *.vm  
  
veloctiy -b *.vm  
 

源碼中test/web/目錄的js，一部分就是線下編譯後的得到的，此處可直接存取。

Public APInode_module 

 

  
var Velocity = require('../src/velocity');  
  
 
  
//1. 直接解析  
  
Velocity.render('string of velocity', context);  
  
 
  
//2. 使用Parser和Compile  
  
var Parser = Velocity.Parser;  
  
var Compile = Velocity.Compile;  
  
 
  
var asts = Parser.parse('string of velocity');  
  
(new Compile(asts)).render(context);  
 

context

context是一個對象，可以為空白，執行中$foo.bar，訪問路徑是context.foo.bar， context的屬性可以是函數，和vm中定義保持一致。

On Broswer

1 . 使用線下打包方案：

 

 

  
KISSY.use('velocity/index, web/directives', function(S, Velocity, asts){  
  
  var compile = new Velocity(asts);  
  
  S.all('body').html(compile.render());  
  
});  
 

2 . 使用線上編譯：

 

 

  
KISSY.use('velocity/index, velocity/parse', function(S, Velocity, Parser){  
  
  var html = (S.all('#tpl').html());  
  
  var asts = Parser.parse(html);  
  
  var compile = new Velocity(asts);  
  
  console.log(compile.render());  
  
});  
 

兩者的區別在於asts的擷取，第一種方式，直接取asts，第二種，需要首先執行文法分析過 程。

Syntax

具體文法請訪問官網文檔：velocity user guide。

Directives

Directives支援set, foreach, if|else|elseif, macro, parse, break。不 支援有，stop, evaluate, define，感覺這些文法比較偏，用處不大，暫時沒有實現。 其中parse，在web端，使用kissy的模組載入器載入，需要首先線下編譯打包，例子。

macro

宏分為系統的宏，比如parse, include，和使用者自訂宏，通過#macro在vm中定義，此 外可以使用自訂的js函數替代在vm中定義。對於系統宏和自訂宏，不做區分，對於 #parse和#include的調用，可以使用自訂函數來執行。具體見issue #3。

foreach

foreach在velocity中對對象的遍曆，和js有區別，java中對象是一個map，需要通過方法 keyset來擷取map中的key，foreach迴圈寫法等同於js的for in迴圈，感覺有點怪異。在 一個foreach，有一個$foreach的對象可以使用，此變數範圍為當前迴圈範圍。

 

  
#foreach($num in [1..5])  
  
  index => $foreach.index   
  
  count => $foreach.count  
  
  #if (!$foreach.hasNext) end #end  
  
#end  
  
結果：  
  
index => 0  
  
count => 1  
  
 
  
index => 1  
  
count => 2  
  
...  
  
index => 4  
  
count => 5  
  
end  
 

string

velocity中字串求值和php類似，雙引號字串裡面的變數會被替換變數對應的值，單引 號原樣返回，推薦盡量使用單引號，那樣效能好一些。此外，雙引號中變數替換，沒有再次 調用文法分析器，而是使用正則，只支援簡單的引用替換，比如"$varname1 $foo.bar"， "$foo.bar[1] $foo.bar()"都不支援。如果需要完整支援字串雙引號，需要反覆調用語 法分析器，考慮到效能，基本引用基本夠用了，vm本身支援強大的變數賦值，可以先賦值， 在放入字串，或者使用加法進行字串拼接。

在java中可能大量使用雙引號方式，因為java對象無法自動轉換類型，雙引號做類型轉換用， 而在web端，js無此需要。

velocity

 

  
Usage: velocity [options] [file ...]  
  
 
  
Options:  
  
 
  
  -h, --help         output usage information  
  
  -V, --version      output the version number  
  
  -b, --build        build .vm file to js ast module of kissy  
  
 
  
Example:  
  
 
  
  # parse vm file  
  
  $ velocity a.vm   
  
 
  
  # parse vm file with json data  
  
  $ velocity a.vm  a.json  
  
 
  
  # build asts module of kissy  
  
  $ velocity *.vm  
 

Helper

Helper提供一些額外的功能，主要用於解決vm資料類比問題。

• structure 擷取vm中所有變數的結構: $foo.bar => foo: {bar: 'string'}
• backstep vm逆推，根據velocity檔案和解析後的結果，計算資料結構和內容
• jsonify 把vm轉換為json結構，去除其中的html標籤，比如：

jsonify文檔issue #11

 

  
hello world $foo.name.  
  
=>  
  
{foo: { name: $foo.name }}  
 

License

(The MIT License)

Copyright (c) 2012-2013 Eward Songeward.song@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

來自：https://github.com/shepherdwind/velocity.js