Skip to content

Latest commit

 

History

History
186 lines (123 loc) · 4.35 KB

api.md

File metadata and controls

186 lines (123 loc) · 4.35 KB

API

ETpl 是一个多 Engine 实例的模板引擎。初始化时其自动创建一个默认的 Engine 实例，并将其暴露。大多数应用场景可直接使用默认的引擎实例。

var etpl = require( 'etpl' );

你也可以通过 new etpl.Engine 初始化自己的引擎实例。 不同的引擎实例可有效避免target命名冲突的问题。

var etpl = require( 'etpl' );
var etplEngine = new etpl.Engine();

引擎实例的初始化允许传入引擎参数。支持的引擎参数见下面的config方法。

var etpl = require( 'etpl' );
var etplEngine = new etpl.Engine({
    commandOpen: '<%',
    commandClose: '%>'
});

下面是 Engine 的实例方法列表。

addCommand

{void} addCommand( {string}name, {Object}command )

常用 自定义命令标签。

  • {string}name - 命令标签名称
  • {Object}command - 命令对象

command 参数是一个对象，包含一些在命令标签编译时各个阶段的处理方法。

  • init(context) - 初始化
  • open(context) - 标签起始
  • close(context) - 标签闭合
  • getRendererBody():string - 生成编译代码
etpl.addCommand('dump', {
    init: function () {
        var match = this.value.match(/^\s*([a-z0-9_]+)\s*$/i);
        if (!match) {
            throw new Error('Invalid ' + this.type + ' syntax: ' + this.value);
        }

        this.name = match[1];
        this.cloneProps = ['name'];
    },

    open: function (context) {
        context.stack.top().addChild(this);
    },

    getRendererBody: function () {
        var util = etpl.util;
        var options = this.engine.options;
        return util.stringFormat(
            'console.log({0});',
            util.compileVariable(options.variableOpen + this.name + options.variableClose, this.engine)
        );
    }
});

addFilter

{void} addFilter( {string}name, {function({string}, {...*}):string}filter )

常用 为默认引擎添加过滤器。过滤函数的第一个参数为过滤源字符串，其后的参数可由模板开发者传入。过滤函数必须返回string。

  • {string}name - 过滤器名称
  • {Function}filter - 过滤函数
etpl.addFilter( 'markdown', function ( source, useExtra ) {
    // ......
} );

compile

{Function} compile( {string}source )

常用 使用默认引擎编译模板。返回第一个target编译后的renderer函数。

  • {string}source - 模板源代码
var helloRenderer = etpl.compile( 'Hello ${name}!' );
helloRenderer( {name: 'ETPL'} ); // Hello ETPL!

config

{void} config( {Object}options )

常用 对默认引擎进行配置，配置参数将合并到引擎现有的参数中。查看配置参数。

etplEngine.config( {
    defaultFilter: ''
} );

getRenderer

{Function} getRenderer( {string}name )

常用 从默认引擎中，根据target名称获取编译后的renderer函数。

  • {string}name - target名称
etpl.compile( '<!-- target: hello -->Hello ${name}!' );
var helloRenderer = etpl.getRenderer( 'hello' );
helloRenderer( {name: 'ETPL'} ); // Hello ETPL!

load

{Function} load( {string}name )

仅node环境 加载并编译target文件

  • {string}name - target名称
var mainRenderer = etpl.load( 'main' );
mainRenderer( {name: 'ETPL'} );

loadFromFile

{Function} loadFromFile( {string}file )

仅node环境 加载并编译模板文件

  • {string}file - 模板文件路径
var mainRenderer = etpl.loadFromFile( path.resolve(__dirname, 'main.etpl') );
mainRenderer( {name: 'ETPL'} );

parse

同compile方法。该方法的存在是为了兼容老版本的模板引擎api，不建议使用。

render

{string} render( {string}name, {Object}data )

使用默认引擎执行模板渲染，返回渲染后的字符串。

  • {string}name - target名称
  • {Object}data - 模板数据。可以是plain object，也可以是带有 {string}get({string}name) 方法的对象
etpl.compile( '<!-- target: hello -->Hello ${name}!' );
etpl.render( 'hello', {name: 'ETPL'} ); // Hello ETPL!