前端模板 art-template API，调试，配置等其他应用

[TOC]
## art-template 接口和配置介绍

### art-template API
#### template(filename, content)
根据模板文件路径渲染模板

+ 参数

|名称|类型|说明|
|--|--|--|
|filename|string|模板文件路径|
|content|Object/string|传递到模板的数据内容|

+ 返回值：content参数传的是对象则`渲染`模板并返回`string`

```js
//编译和缓存
template('/welcome.art', 'hi, <%=value%>.');
```

+ 返回值：content参数传的是字符串则`编译`模板返回`function`

```js
var html = template('/welcome.art', {
    value: 'aui'
});
```

+ 浏览器版本不能读取文件，filename为存放模板的元素id

#### compile(source, options)
编译模板并返回一个渲染函数

+ 参数

|名称|类型|说明|
|--|--|--|
|source|string|模板内容|
|options|Object|可选参数|

+ 返回一个渲染函数

```js
//编译
var render = template.compile('hi, <%=value%>.')
//渲染
var html = render({value: 'aui'});
```

#### render(source, data, options)
编译并返回渲染结果

+ 参数

+ 返回一个渲染函数

```js
var html = template.render('hi, <%=value%>.', {value: 'aui'})
```
#### .defaults

Object类型，模板引擎默认配置参考[选项](#h3-art-template-)

#### .extension
Object类型，给 NodeJS require.extensions 注册的模板渲染函数,此功能仅对 NodeJS 生效，如果要在浏览器中使用模板文件渲染功能，请使用[Webpack art-template-loader](https://aui.github.io/art-template/zh-cn/webpack/)

+ 默认注册`.art`

```js
var template = require('art-template');
var view = require('./index.art');
var html = view(data);
```

+ 加载 `.ejs` 模板

```js
var template = require('art-template');
require.extensions['.ejs'] = template.extension;
var view = require('./index.ejs');
var html = view(data);
```

### art-template 可配置选项
可配置选项为`template.defaults`对象下属性

```js
// 模板名
filename: null,
// 模板语法规则列表
rules: [nativeRule, artRule],
// 是否开启对模板输出语句自动编码功能。为 false 则关闭编码输出功能
// escape 可以防范 XSS 攻击
escape: true,
// 启动模板引擎调试模式。如果为 true: {cache:false, minimize:false, compileDebug:true}
debug: detectNode ? process.env.NODE_ENV !== 'production' : false,
// bail 如果为 true，编译错误与运行时错误都会抛出异常
bail: true,
// 是否开启缓存
cache: true,
// 是否开启压缩。它会运行 htmlMinifier，将页面 HTML、CSS、CSS 进行压缩输出
// 如果模板包含没有闭合的 HTML 标签，请不要打开 minimize，否则可能被 htmlMinifier 修复或过滤
minimize: true,
// 是否编译调试版
compileDebug: false,
// 模板路径转换器
resolveFilename: resolveFilename,
// 子模板编译适配器
include: include,
// HTML 压缩器。仅在 NodeJS 环境下有效
htmlMinifier: htmlMinifier,
// HTML 压缩器配置。参见 https://github.com/kangax/html-minifier
htmlMinifierOptions: {
 collapseWhitespace: true,
 minifyCSS: true,
 minifyJS: true,
 // 运行时自动合并：rules.map(rule => rule.test)
 ignoreCustomFragments: []
},
// 错误事件。仅在 bail 为 false 时生效
onerror: onerror,
// 模板文件加载器
loader: loader,
// 缓存中心适配器（依赖 filename 字段）
caches: caches,
// 模板根目录。如果 filename 字段不是本地路径，则在 root 查找模板
root: '/',
// 默认后缀名。如果没有后缀名，则会自动添加 extname
extname: '.art',
// 忽略的变量。被模板编译器忽略的模板变量列表
ignore: [],
// 导入的模板变量
imports: runtime
```
### art-template 调试
art-template内置了调试器，可捕获语法异常和运行错误，设置`template.defaults.debug = true`，在Nodejs环境中开启调试会开启`process.env.NODE_ENV !== 'production'`,非生成环境下才能进行调试，设置后对应等于设置了下面几项
```json
{
 "cache": false,
 "minimize": false,
 "compileDebug": true
}
```
### art-template 模板变量
#### 内置变量清单
+ $data 传入模板的数据
+ $imports 外部导入的变量以及全局变量
+ print 字符串输出函数
+ include 子模板载入函数
+ extend 模板继承模板导入函数
+ block 模板块声明函数

#### 添加自定义变量
通过对`template.defaults.imports`扩展添加
```js
template.defaults.imports.log = console.log;
```
### art-template 解析模板的规则
#### 默认规则
art-template 默认有原始语法`<% %>`和标准语法`{{}}`两种解析规则，除此之外也可以自定义模板规则
```js
// 原始语法的界定符规则
template.defaults.rules[0].test = /<%(#?)((?:==|=#|[=-])?)[ \t]*([\w\W]*?)[ \t]*(-?)%>/;
// 标准语法的界定符规则
template.defaults.rules[1].test = /{{([@#]?)[ \t]*(\/?)([\w\W]*?)[ \t]*}}/;
```
从上面代码中也可以对默认语法经行修改，例如将`<%=%>`替换为`<? ?>`
```js
var rule = template.defaults.rules[0];
rule.test = new RegExp(rule.test.source.replace('<%', '<\\\?').replace('%>', '\\\?>'));
```
#### 自定义规则
添加一个ES6 ${name} 模板字符串的解析
```js
template.defaults.rules.push({
 test: /\${([\w\W]*?)}/,
 use: function(match, code) {
 return {
 code: code,
 output: 'escape'
 }
 }
});
```
test 是匹配字符串正则，use 是匹配后的调用函数
use 函数说明

- 参数：一个参数为匹配到的字符串，其余的参数依次接收 test 正则的分组匹配内容
- 返回值：必须返回一个对象，包含 code 与 output 两个字段
  * code 转换后的 JavaScript 语句
  * output 描述 code 的类型，可选值
   + `escape` 编码后进行输出
   + `raw` 输出原始内容
   + false 不输出任何内容

### art-template 压缩页面
art-template可以对css，js，html文件进行压缩，设置`template.defaults.minimize = true` 即可
详细配置参见：https://github.com/kangax/html-minifier
默认配置
```js
template.defaults.htmlMinifierOptions = {
    collapseWhitespace: true,
    minifyCSS: true,
    minifyJS: true,
    // 运行时自动合并：rules.map(rule => rule.test)
    ignoreCustomFragments: []
}
```