1 | Velocity - Template Engine
|
2 | ==========================
|
3 |
|
4 |
|
5 | [![NPM version][npm-image]][npm-url]
|
6 | [![build status][travis-image]][travis-url]
|
7 | [![Test coverage][coveralls-image]][coveralls-url]
|
8 | [![npm download][download-image]][download-url]
|
9 |
|
10 | [npm-image]: http://img.shields.io/npm/v/velocityjs.svg?style=flat-square
|
11 | [npm-url]: http://npmjs.org/package/velocityjs
|
12 | [download-image]: https://img.shields.io/npm/dm/velocityjs.svg?style=flat-square
|
13 | [download-url]: https://npmjs.org/package/velocityjs
|
14 | [travis-image]: https://img.shields.io/travis/shepherdwind/velocity.js.svg?style=flat-square
|
15 | [travis-url]: https://travis-ci.org/shepherdwind/velocity.js
|
16 | [coveralls-image]: https://img.shields.io/coveralls/shepherdwind/velocity.js.svg?style=flat-square
|
17 | [coveralls-url]: https://coveralls.io/r/shepherdwind/velocity.js?branch=master
|
18 |
|
19 |
|
20 | Velocityjs is [velocity](http://velocity.apache.org/) template engine for javascript.
|
21 |
|
22 | [中文版文档](./README-cn.md)
|
23 |
|
24 | ##Features
|
25 |
|
26 | - Supports both client and server side use.
|
27 | - Separation of parsing and rendering templates.
|
28 | - The basic syntax is fully supported all java version velocity.
|
29 | - [Vim Syntax](https://github.com/shepherdwind/vim-velocity) for vim.
|
30 |
|
31 | ##Install
|
32 |
|
33 | via npm:
|
34 |
|
35 | ```bash
|
36 | $ npm install velocityjs
|
37 | ```
|
38 |
|
39 | ##Broswer
|
40 |
|
41 | Compatible all modern broswer, You can try [test case](http://git.shepherdwind.com/velocity.js/runner/tests.html) on your browser to test it.
|
42 |
|
43 | For other lower version broswer, you need have those polyfill function.
|
44 |
|
45 | 1. Array.prototype map, forEach, some, filter, every, indexOf
|
46 | 2. Date.now
|
47 | 3. Object.keys
|
48 |
|
49 | ##Examples
|
50 |
|
51 | You can find a lot of examples from the tests directory. There is no different between the use of browser and NodeJs.
|
52 |
|
53 | ##Public API
|
54 |
|
55 | ```
|
56 | {
|
57 | // render method
|
58 | render(vm: string, context?: Object, macros?: Object): string;
|
59 |
|
60 | parse(vm: string, config?: Object, ignorespace?: boolean): Array<Ast>;
|
61 |
|
62 | Compile: {
|
63 | (asts: Array<Ast>, config?: Object): {
|
64 | render(context?: Object, macros?: Object);
|
65 | };
|
66 | };
|
67 | }
|
68 | ```
|
69 |
|
70 | ### render
|
71 |
|
72 | params:
|
73 |
|
74 | - vm {string} velocity string input
|
75 | - context {object} render context, data or function for vm
|
76 | - macros {object} such as `#include('path/xxx')` , you can define you `inlcude` macro function
|
77 |
|
78 | ```js
|
79 | var Velocity = require('velocityjs');
|
80 |
|
81 | Velocity.render('string of velocity', context, macros);
|
82 | ```
|
83 |
|
84 | ####context
|
85 |
|
86 | `context` is an object or undefined, for vm `$foo.bar`, data look up path will be `context.foo.bar`.
|
87 | `context` can have method, and call it just on velocity string.
|
88 |
|
89 | The method of context, will have `eval` method on `this` of inner method body. You can `eval` to rerender velocity string, such as test code [$control.setTemplate](https://github.com/shepherdwind/velocity.js/blob/master/tests/compile.js#L532).
|
90 |
|
91 |
|
92 | ### Compile and parse
|
93 |
|
94 | `parse` method can parse vm, and return ast tree of velocity.
|
95 |
|
96 | `Compile` will render asts to result string.
|
97 |
|
98 | ```
|
99 | var Compile = Velocity.Compile;
|
100 |
|
101 | var asts = Velocity.parse('string of velocity');
|
102 | (new Compile(asts)).render(context, macros);
|
103 | ```
|
104 |
|
105 | #### Compile
|
106 |
|
107 | params:
|
108 |
|
109 | - asts {array} array of vm asts tree
|
110 | - config {object} you can define some option for Compile
|
111 |
|
112 | ##### config
|
113 |
|
114 | - escape {boolean} default `true`, default escape variable to html encode, you can set false to close it.
|
115 | - unescape {object} define the object, which key do not need escape. For example, set unescape equal `{control: true}`, so `$control.html` will not escape.
|
116 | - env {string} when env equal `development` will throw error when null values are used
|
117 |
|
118 | #### parse
|
119 |
|
120 | params:
|
121 |
|
122 | - vm {string} string to parse
|
123 | - blocks {object} self define blocks, such as `#cms(1) hello #end`, you can set `{cms: true}`
|
124 | - ignorespace {boolean} if set true, then ignore the newline trim.
|
125 |
|
126 | ##Syntax
|
127 |
|
128 | Syntax you can find from [velocity user guide](http://velocity.apache.org/engine/devel/user-guide.html)。
|
129 |
|
130 | ###Directives
|
131 |
|
132 | Directives supports have `set`, `foreach`, `if|else|elseif`, `macro`, `break`, `stop`.
|
133 |
|
134 | Some othe directive `evaluate`, `define`, `parse`, do not supported default, but You can realize by context or macros, for example [parse](https://github.com/shepherdwind/velocity.js/blob/master/tests/compile.js#L627)
|
135 |
|
136 | ##Questions
|
137 |
|
138 | You can find help from those ways:
|
139 |
|
140 | 1. New [issue](https://github.com/shepherdwind/velocity.js/issues/new)
|
141 | 2. Email to eward.song at gmail.com
|
142 | 3. 阿里内部员工,可以通过 hanwen.sah 搜到我的旺旺
|
143 |
|
144 | ## Other
|
145 |
|
146 | Recommend an other [velocity](https://github.com/fool2fish/velocity).
|
147 |
|
148 | ##License
|
149 |
|
150 | (The MIT License)
|