注意

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

查看最新版本

$ npm info velocityjs version 

Velocity.js 是velocity模板語法的javascript實(shí)現(xiàn)。Velocity 是基于Java的模板引擎，廣泛應(yīng)用在阿里集 體各個(gè)子公司。Velocity模板適用于大量模板使用的場(chǎng)景，支持復(fù)雜的邏輯運(yùn)算，包含 基本數(shù)據(jù)類型、變量賦值和函數(shù)等功能。Velocity.js 支持 Node.js 和瀏覽器環(huán)境。

最新版下載地址：https://github.com/shepherdwind/velocity.js/zipball/master

Features

• 支持客戶端和服務(wù)器端使用

• 語法是富邏輯的，構(gòu)成門微型的語言

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

• 基本完全支持velocity語法

• 瀏覽器使用支持模板之間相互引用，依據(jù)kissy模塊加載機(jī)制

• 三個(gè)Helper，友好的數(shù)據(jù)模擬解決方案

• Vim Syntax

Install

via npm:

$ npm install velocityjs 

Broswer Support

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

點(diǎn)擊此處可以體驗(yàn)web 端velocity語法解析過程，注：使用ACE作為代碼編輯器，僅支持高級(jí)瀏覽器訪問。

執(zhí)行cake命令進(jìn)行打包velocity.js瀏覽器端腳本:

$ make parse  

需要cli下安裝coffeejs，暫時(shí)打包是為kissy所使用的，velocity.js需要的一些常用的 ecma5功能，比如foreach, some, isArray等，在node環(huán)境下是自帶的功能，而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語法具有很高的容錯(cuò)能力，類似于html結(jié)構(gòu)的解析，同時(shí)語法規(guī)則復(fù)雜，所以語法 解釋器執(zhí)行性能可能比較慢，velocity.js把語法結(jié)構(gòu)分析運(yùn)算和語法執(zhí)行兩個(gè)過程獨(dú)立出來， 第一步，語法結(jié)構(gòu)分析返回一個(gè)數(shù)組(語法樹)，描述velocity語法，語法執(zhí)行使用數(shù)據(jù)和語 法樹，計(jì)算模板最終結(jié)果。

執(zhí)行build后，得到兩個(gè)文件，分別是build/velocity/下的index.js和parse.js，兩者 相互獨(dú)立，parse.js語法分析過程可以放在本地完成，執(zhí)行命令：

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

雖然語法解釋器可以在瀏覽器端執(zhí)行，但是，不推薦那么使用。

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

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

Public API

node_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是一個(gè)對(duì)象，可以為空，執(zhí)行中$foo.bar，訪問路徑是context.foo.bar， context的屬性可以是函數(shù)，和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());  
});  

兩者的區(qū)別在于asts的獲取，第一種方式，直接取asts，第二種，需要首先執(zhí)行語法分析過 程。

Syntax

具體語法請(qǐng)?jiān)L問官網(wǎng)文檔：velocity user guide。

Directives

Directives支持set, foreach, if|else|elseif, macro, parse, break。不 支持有，stop, evaluate, define，感覺這些語法比較偏，用處不大，暫時(shí)沒有實(shí)現(xiàn)。 其中parse，在web端，使用kissy的模塊加載器加載，需要首先線下編譯打包，例子。

macro

宏分為系統(tǒng)的宏，比如parse, include，和用戶自定義宏，通過#macro在vm中定義，此 外可以使用自定義的js函數(shù)替代在vm中定義。對(duì)于系統(tǒng)宏和自定義宏，不做區(qū)分，對(duì)于 #parse和#include的調(diào)用，可以使用自定義函數(shù)來執(zhí)行。具體見issue #3。

foreach

foreach在velocity中對(duì)對(duì)象的遍歷，和js有區(qū)別，java中對(duì)象是一個(gè)map，需要通過方法 keyset來獲取map中的key，foreach循環(huán)寫法等同于js的for in循環(huán)，感覺有點(diǎn)怪異。在 一個(gè)foreach，有一個(gè)$foreach的對(duì)象可以使用，此變量作用域?yàn)楫?dāng)前循環(huán)范圍。

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

string

velocity中字符串求值和php類似，雙引號(hào)字符串里面的變量會(huì)被替換變量對(duì)應(yīng)的值，單引 號(hào)原樣返回，推薦盡量使用單引號(hào)，那樣性能好一些。此外，雙引號(hào)中變量替換，沒有再次 調(diào)用語法分析器，而是使用正則，只支持簡(jiǎn)單的引用替換，比如"$varname1 $foo.bar"， "$foo.bar[1] $foo.bar()"都不支持。如果需要完整支持字符串雙引號(hào)，需要反復(fù)調(diào)用語 法分析器，考慮到性能，基本引用基本夠用了，vm本身支持強(qiáng)大的變量賦值，可以先賦值， 在放入字符串，或者使用加法進(jìn)行字符串拼接。

在java中可能大量使用雙引號(hào)方式，因?yàn)閖ava對(duì)象無法自動(dòng)轉(zhuǎn)換類型，雙引號(hào)做類型轉(zhuǎn)換用， 而在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數(shù)據(jù)模擬問題。

• structure 獲取vm中所有變量的結(jié)構(gòu): $foo.bar => foo: {bar: 'string'}
• backstep vm逆推，根據(jù)velocity文件和解析后的結(jié)果，計(jì)算數(shù)據(jù)結(jié)構(gòu)和內(nèi)容
• jsonify 把vm轉(zhuǎn)換為json結(jié)構(gòu)，去除其中的html標(biāo)簽，比如：

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