dbox-velocity-js v0.4.3

Velocity - Template Engine

Note

velocityjs in npm package name changed from the original velocity.js velocityjs, feel require ("velocity.js") comparison does not look good, so renamed from versions after 0.3.0 update in velocityjs.

View the latest edition

$ npm info velocityjs version

velocity.js is the velocity template syntax javascript implementation. Velocity is a Java-based template engine, widely used in various subsidiaries Ali collective. Velocity template template applies to a large number of scenarios to support complex logic operations, including basic data types, variables, and functions assigned functions.

##Features

• Supports both client and server side use
• The syntax is rich logic, language constitutes a tiny door
• Separation of parsing and rendering templates
• The basic syntax is fully supported velocity
• The browser uses the mutual support between a reference template based js module loading mechanisms, such kissy Three Helper, friendly data analog solutions
• Vim Syntax

##Install

via npm:

$ npm install velocityjs

##Broswer Support

Compatible ie6 +, chrome and other browsers, test case

Click here can experience the web Terminal velocity parsing process, Note: Use the ACE as a code editor, only supports advanced browser.

Cake command execution packaged velocity.js browser side script:

$ make parse

Installation requires cli under coffeejs, temporary package is used for the kissy, velocity.js ecma5 need some common features, such as foreach, some, isArray, etc., in the node environment comes with features, and is cross-compatible web client to solve the existing library. Need to provide their own set of cross-browser api, such as kissy package:

  //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 syntax with high fault tolerance, similar to parse html structure, while the complex rules of grammar, syntax so The interpreter execution performance may be slower, velocity.js the analysis algorithms perform syntax and grammatical structure of two independent processes, The first step, grammatical structure analysis returns an array (syntax tree), describing velocity grammar, syntax and pragmatics performed using data Law tree calculation template final result.

After executing build, get two documents, namely index.js and parse.js build / velocity / under both Independent of each other, parse.js parsing process can be placed locally, run the command:

The parsing and template stitching apart, in order to facilitate the local compiler syntax tree, reduce web side js operations. Local compilation Ideas template from KISSY of xtemplate.

Although the syntax interpreter can be executed in the browser, but it is not recommended to use.

# Using the velocity command line tools packaged
veloctiy --build *.vm
veloctiy -b *.vm

Js source in test/web/ directory, the line is part of the compiled obtained here directly.http://shepherdwind.com/velocity/web/index.html)。

##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 is an object that can be empty, running $foo.bar, the access path is context.foo.bar, context attributes can be functions, and define vm consistent.

###On Broswer

1 . The next line of packaged solutions using：

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

2 . Use online compilation：

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());
});

The difference is that asts acquisition, the first approach, direct access asts, second, you need to first perform parsing process.

##Syntax

Concrete syntax, please visit the official website document：velocity user guide。

###Directives

Directives Support set, foreach, if|else|elseif, macro, parse, breakThere is not supported，stop, evaluate, define，These grammar feel more biased, less useful, there is no implementation. Wherein parse，In the web side, use kissy module loader loads, you need to compile packaging line，Example。

###macro

Macros macro into the system, such asparse, include，And user-defined macros, by#macroDefined in the vm, this Js function can be used outside of a custom alternative defined in the vm. For system macros and custom macros, no distinction, for call #parse and #include, you can use a custom function to perform. See in particularissue #3。

###foreach

foreach in the velocity of the object traversal, and js differentiated, java objects in a map, through methods keyset to get the map of the key, foreach loop wording identical to the js for in the cycle, I feel a little weird. In A foreach, there is a $ foreach object can be used, this variable is scoped to the current cycle range.

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

index => 1
count => 2
...
index => 4
count => 5
end

###string

velocity evaluated and php string similar variables inside double-quoted string value of the variable will be replaced with the corresponding single-lead No returns intact, it is recommended to make use of single quotation marks, as good as some of the properties. In addition, variable substitution in double quotes, no again Call the parser, but the use of regular, replace only support simple references, such as " $ varname1 $ foo.bar ", " $ foo.bar [1] $ foo.bar () " do not support. If you need the full support of the string in double quotes, words need to repeatedly call Law analyzer, taking into account the performance of the basic references basic enough, vm itself supports powerful variable assignment, you can first assignment, Being placed in a string, or use the addition for string stitching.

In a lot of java may use double quotes way because not automatically convert java object type, use double quotes do type conversion, In the web client, js no such need.

###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 provides some additional features, mainly used to solve the problem vm simulation data.

• Structure vm get all the variables in the structure: $ foo.bar => foo: {bar: 'string'}
• Backstep vm thrusting, according to the results of velocity documents and parsed to calculate the data structure and content
• Jsonify vm converted to json structure to remove one of the html tag, for example:

jsonify Documentationissue #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.