Velocity.js —— 來(lái)自淘寶的 JS 模板引擎
注意
velocityjs在npm中包名從原來(lái)的velocity.js改為velocityjs，感覺require("velocity.js") 比較不好看，所以改名，從0.3.0之后的版本都在velocityjs下更新。
查看最新版本
- $ npm info velocityjs version
Velocity.js 是velocity模板語(yǔ)法的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ù)器端使用
-
語(yǔ)法是富邏輯的，構(gòu)成門微型的語(yǔ)言
-
語(yǔ)法分析和模板渲染分離
-
基本完全支持velocity語(yǔ)法
-
瀏覽器使用支持模板之間相互引用，依據(jù)kissy模塊加載機(jī)制
-
三個(gè)Helper，友好的數(shù)據(jù)模擬解決方案
Install
via npm:
- $ npm install velocityjs
Broswer Support
兼容ie6+，chrome等其他瀏覽器，test case
點(diǎn)擊此處可以體驗(yàn)web 端velocity語(yǔ)法解析過(guò)程，注：使用ACE作為代碼編輯器，僅支持高級(jí)瀏覽器訪問(wèn)。
執(zhí)行cake命令進(jìn)行打包velocity.js瀏覽器端腳本:
- $ make parse
需要cli下安裝coffeejs，暫時(shí)打包是為kissy所使用的，velocity.js需要的一些常用的 ecma5功能，比如foreach, some, isArray等，在node環(huán)境下是自帶的功能，而web端的兼 容是交給已有的類庫(kù)解決。需要自行提供一組跨瀏覽器的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語(yǔ)法具有很高的容錯(cuò)能力，類似于html結(jié)構(gòu)的解析，同時(shí)語(yǔ)法規(guī)則復(fù)雜，所以語(yǔ)法 解釋器執(zhí)行性能可能比較慢，velocity.js把語(yǔ)法結(jié)構(gòu)分析運(yùn)算和語(yǔ)法執(zhí)行兩個(gè)過(guò)程獨(dú)立出來(lái)， 第一步，語(yǔ)法結(jié)構(gòu)分析返回一個(gè)數(shù)組(語(yǔ)法樹)，描述velocity語(yǔ)法，語(yǔ)法執(zhí)行使用數(shù)據(jù)和語(yǔ) 法樹，計(jì)算模板最終結(jié)果。
執(zhí)行build后，得到兩個(gè)文件，分別是build/velocity/下的index.js和parse.js，兩者 相互獨(dú)立，parse.js語(yǔ)法分析過(guò)程可以放在本地完成，執(zhí)行命令：
把語(yǔ)法分析和模板拼接分開，為了方便在本地編譯語(yǔ)法樹，減少在web端js運(yùn)算。本地編譯 模板的思路，源自KISSY的xtemplate。
雖然語(yǔ)法解釋器可以在瀏覽器端執(zhí)行，但是，不推薦那么使用。
- #使用velocity命令行工具打包
- veloctiy --build *.vm
- veloctiy -b *.vm
源碼中test/web/目錄的js，一部分就是線下編譯后的得到的，此處可直接訪問(wèn)。
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，訪問(wèn)路徑是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í)行語(yǔ)法分析過(guò) 程。
Syntax
具體語(yǔ)法請(qǐng)?jiān)L問(wèn)官網(wǎng)文檔：velocity user guide。
Directives
Directives支持set, foreach, if|else|elseif, macro, parse, break。不 支持有，stop, evaluate, define，感覺這些語(yǔ)法比較偏，用處不大，暫時(shí)沒(méi)有實(shí)現(xiàn)。 其中parse，在web端，使用kissy的模塊加載器加載，需要首先線下編譯打包，例子。
macro
宏分為系統(tǒng)的宏，比如parse, include，和用戶自定義宏，通過(guò)#macro在vm中定義，此 外可以使用自定義的js函數(shù)替代在vm中定義。對(duì)于系統(tǒng)宏和自定義宏，不做區(qū)分，對(duì)于 #parse和#include的調(diào)用，可以使用自定義函數(shù)來(lái)執(zhí)行。具體見issue #3。
foreach
foreach在velocity中對(duì)對(duì)象的遍歷，和js有區(qū)別，java中對(duì)象是一個(gè)map，需要通過(guò)方法 keyset來(lái)獲取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)中變量替換，沒(méi)有再次 調(diào)用語(yǔ)法分析器，而是使用正則，只支持簡(jiǎn)單的引用替換，比如"$varname1 $foo.bar"， "$foo.bar[1] $foo.bar()"都不支持。如果需要完整支持字符串雙引號(hào)，需要反復(fù)調(diào)用語(yǔ) 法分析器，考慮到性能，基本引用基本夠用了，vm本身支持強(qiáng)大的變量賦值，可以先賦值， 在放入字符串，或者使用加法進(jìn)行字符串拼接。
在java中可能大量使用雙引號(hào)方式，因?yàn)閖ava對(duì)象無(wú)法自動(dòng)轉(zhuǎn)換類型，雙引號(hào)做類型轉(zhuǎn)換用， 而在web端，js無(wú)此需要。
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ù)模擬問(wèn)題。
structure獲取vm中所有變量的結(jié)構(gòu):$foo.bar=>foo: {bar: 'string'}backstepvm逆推，根據(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.
來(lái)自：https://github.com/shepherdwind/velocity.js
