聂文文学习笔记-doT

doT.js

The fastest + concise javascript template engine for Node.js and browsers.
Node.js和browsers下最快速+简洁的javascript模板引擎．

Origins 起源

doT.js was created in search of the fastest and concise JavaScript templating function with emphasis on performance under V8 and Node.js. It shows great performance for both Node.js and browsers.
doT.js 创建是为了寻找最快和简洁 JavaScript 模板功能，并强调 V8 和 Node.js 下的性能．

灵感来自两个引擎 jQote2和underscore.js．

doT.js is fast, small and has no dependencies.

doT.js快速，内存小，并且没有依赖．

Features 特征

• no dependencies, 120 loc 没有依赖,(120 loc，不知道什么意思？单位？)
• extremely fast 相当快
• custom delimiters 自定义分隔符
• runtime evaluation 运行时求值
• runtime interpolation 运行时赋值
• compile-time evaluation 编译时求值
• partials support partials支持(partials,代码块？)
• conditionals support 支持条件语句
• array iterators 数组迭代器
• encoding 编码
• control whitespace - strip or preserve 控制或保留空白
• streaming friendly 流媒体友好

Usage 使用说明

这里是重点

interpolation 赋值

• Template

<div>Hi {{=it.name}}!</div>
<div>{{=it.age || ''}}</div>

• doT.template compiles it into

function anonymous(it /**/) { var out='<div>Hi '+(it.name)+'!</div><div>'+ (it.age || '')+'</div>';return out; }

• Data

{"name":"Jake","age":31}

• Result

<div>Hi Jake!</div><div>31</div>

evaluation 求值

• Template

{{ for(var prop in it) { }}
<div>{{=prop}}</div>
{{ } }}

• doT.template compiles it into

function anonymous(it /**/) { var out=''; for(var prop in it) { out+='<div>'+(prop)+'</div>'; } return out; }

• Data

{"name":"Jake","age":31,"mother":"Kate","father":"John","interests":["basketball","hockey","photography"],"contact":{"email":"jake@xyz.com","phone":"999999999"}}

• Result

<div>name</div><div>age</div><div>mother</div><div>father</div><div>interests</div><div>contact</div>

partials

• Template

{{##def.snippet:
<div>{{=it.name}}</div>{{#def.joke}}
#}}

{{#def.snippet}}

• Compile-time defines (def)

{"joke":"<div>{{=it.name}} who?</div>"}

• doT.template compiles it into

function anonymous(it /**/) { var out='<div>'+(it.name)+'</div><div>'+(it.name)+' who?</div>';return out; }

• Data

{"name":"Jake","age":31}

• Result

<div>Jake</div><div>Jake who?</div>

conditionals 条件语句

• Template

{{? it.name }}
<div>Oh, I love your name, {{=it.name}}!</div>
{{?? it.age === 0}}
<div>Guess nobody named you yet!</div>
{{??}}
You are {{=it.age}} and still don't have a name?
{{?}}

• doT.template compiles it into

这一段会导致SQL注入错误，就不写上去了．

• Data

{"name":"Jake","age":31}

• Result

<div>Oh, I love your name, Jake!</div>

arrays 数组

• Template

{{~it.array :value:index}}
<div>{{=value}}!</div>
{{~}}

• doT.template compiles it into

function anonymous(it /**/) { var out='';var arr1=it.array;if(arr1){var value,index=-1,l1=arr1.length-1;while(index<l1){value=arr1[index+=1];out+='<div>'+(value)+'!</div>';} } return out; }  

• Data

{"array":["banana","apple","orange"]}

• Result

<div>banana!</div><div>apple!</div><div>orange!</div>

encode 编码

• Template

Visit {{!it.uri}}

• doT.template compiles it into

function anonymous(it /**/) { var encodeHTML = typeof _encodeHTML !== 'undefined' ? _encodeHTML : (function (b){var a={"&":"&","<":"<",">":">",'"':""","'":"'","/":"/"},d=b?/[&<>"'/]/g:/&(?!#?w+;)|<|>|"|'|//g;return function(b){return b? b.toString().replace(d,function(b){return a[b]||b}):""}}());var out='Visit '+encodeHTML(it.uri);return out; }

• Data

{"uri":"https://github.com/olado/doT"}

• Result

Visit https://github.com/olado/doT

Compile time evaluation vs Runtime evaluation 编译时求值 vs 运行时求值

You can improve performance further if you use compile time evaluation. It is useful in cases when the data that you want to use are not changing with each run of the template. Think of it as defines or constant variables.

你可以提高性能进一步,如果你使用编译时求值.如果你想要使用的数据不随模板每次运行而变化的情况下有用．把它认作定义或常数变量．

It is also used to statically compile partials. This comes in handy when you want to include similar header and footer on multiple pages. doT also allows to customize partial right from the template that will include it.

它也用于静态编译的partials.这派上用场当你想要包括类似的页头和页脚在多个页上．doT也允许从模板自定义partial包含它的权利．

Check advanced sample and one more sample for hints on how to use defines and partials.

点击上面两个链接查看怎么使用defines和partials．

Installation 安装说明

For Node.js (我还不会node.js，先不讨论)

For browsers
Include the javascript file in your source:

<script type="text/javascript" src="doT.js"></script>

Sample

// 1. Compile template function
var tempFn = doT.template("<h1>Here is a sample template {{=it.foo}}</h1>");
// 2. Use template function as many times as you like
var resultText = tempFn({foo: 'with doT'});

API

这里是重点

doT.templateSettings - default compilation settings 默认的编译设置

You can customize doT by changing compilation settings. Here are the default settings:

doT.templateSettings = {
  evaluate:    /{{([sS]+?)}}/g,
  interpolate: /{{=([sS]+?)}}/g,
  encode:      /{{!([sS]+?)}}/g,
  use:         /{{#([sS]+?)}}/g,
  define:      /{{##s*([w.$]+)s*(:|=)([sS]+?)#}}/g,
  conditional: /{{?(?)?s*([sS]*?)s*}}/g,
  iterate:     /{{~s*(?:}}|([sS]+?)s*:s*([w$]+)s*(?::s*([w$]+))?s*}})/g,
  varname: 'it',
  strip: true,
  append: true,
  selfcontained: false
};

If you want to use your own delimiters, you can modify RegEx in doT.templateSettings to your liking.
如果你想要使用你自己的分隔符，你可以根据自己的喜好在 doT.templateSettings 修改正则表达式．　　

Here is the list of default delimiters:
默认分隔符列表：

• {{ }} for evaluation 应该是表达式的意思
• {{= }} for interpolation 赋值
• {{! }} for interpolation with encoding 编码并赋值
• {{# }} for compile-time evaluation/includes and partials 编译时　代码块
• {{## #}} for compile-time defines 编译时定义
• {{? }} for conditionals 条件
• {{~ }} for array iteration 数组迭代器

By default, the data in the template must be referenced with 'it'. To change the default variable name, modify setting 'varname'. For example, if you set 'varname' to "foo, bar" you will be able to pass 2 data instances and refer to them from the template by foo and bar.

默认情况下，模板中的数据必须引用 'it'.若要更改默认变量名称，修改设置 'varname'.例如，如果你将 'varname 设置为"foo，bar"你将能够传递 2 数据实例和引用它们来自模板的 foo 和 bar.

To control whitespace use 'strip' option, true - to strip, false - to preserve.
就是"strip"为true除去空白，为false保留空白．

'append' is a performance optimization setting. It allows to tweak performance, depending on the javascript engine used and size of the template, it may produce better results with append set to false.

'append'是一个性能优化设置．它允许调整性能，取决于使用的 javascript 引擎和模板的尺寸．追加设置为 false，它可能会产生更好的结果．

If 'selfcontained' is true, doT will produce functions that have no dependencies on doT. In general, generated functions have no dependencies on doT, with the exception for encodeHTML and it is only added if encoding is used. If 'selfcontained' is true and template needs encoding, encodeHTML function will be included in the generated template function.

如果 'selfcontained' 为true，doT会产生没有依赖在doT上的功能．一般情况下，生成功能没有依赖在doT上、 例外是encodeHTML 和如果使用了编码，它仅仅添加．如果 'selfcontained' 为 true并且模板需要编码，encodeHTML 函数将包含在生成的模板功能．

doT.template - template compilation function 模板编译函数

Call this function to compile your template into a function.
调用此函数以将你的模板编译成一个函数．

function(tmpl, c, def)

• tmpl - template text 模板文本

• c - custom compilation settings, if null, doT.templateSettings is used
  用户编译设置．如果为null，设置值为之前设定的．

• def - data for compile time evaluation, see advanced sample.
  用来编译时求值的数据，参考成熟的例子．

By default, the produced function expects one parameter - data - with the name 'it'. The names and number of parameters can be changed by changing doT.templateSettings.varname

默认情况下，生产函数需要一个参数-数据-用 'it'命名．名称和参数数目可以通过改变 doT.templateSettings.varname 而改变．

Node module supports auto-compilation of dot templates (还没学过node.js,暂时不讨论)

You can precompile all your templates into modules compatible with commonJS, browsers and AMD.

var dots = require("dot").process({ path: "./views"});

This will compile .def, .dot, .jst files found under the specified path. Details

• Template files can have multiple extensions at the same time.
• Files with .def extension can be included in other files via {{#def.name}}
• Files with .dot extension are compiled into functions with the same name and can be accessed as render. <filename>
• Files with .jst extension are compiled into .js files. Produced .js file can be loaded as a commonJS, AMD module, or just installed into a global variable (default is set to window.render)
• All inline defines defined in the .jst file are compiled into separate functions and are available via render.<filename>.<definename>
• It ignores sub-directories.

Basic usage:

    var dots = require("dot").process({path: "./views"});
    // using .jst files
    var render = require('./views/mytemplate');
    render({foo:"hello world"});
    // using .dot files
    dots.mydottemplate({it: "dot"});

The above snippet will:

• Compile all templates in views folder (.dot, .def, .jst)
• Place .js files compiled from .jst templates into the same folder. These files can be used with require, i.e. require("./views/mytemplate")
• Return an object with functions compiled from .dot templates as its properties
• Render mytemplate template
• Note: compiled files can also be used in the browser

See code example, note there is an index.js file in output directory. It allows you to do things like:

    var render = require('./views');
    render.templateOne(data);
    render.templateTwo(data);

There is a CLI tool that does the same compilation

./bin/dot-packer -s examples/views -d out/views

Author

doT.js by Laura Doktorova, MIT license