xtemplate
Version:
eXtensible Template Engine lib on browser and nodejs. support async control, inheritance, include, logic expression, custom function and more.
359 lines (296 loc) • 7.67 kB
Markdown
# XTemplate API
## Class
XTemplate/XTemplateRuntime
<table class="table table-bordered table-striped">
<thead>
<tr>
<th style="width: 100px;">name</th>
<th style="width: 50px;">type</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td>content</td>
<td>String</td>
<td>template content string</td>
</tr>
<tr>
<td>config</td>
<td>Object</td>
<td>
<table class="table table-bordered table-striped">
<thead>
<tr>
<th style="width: 100px;">name</th>
<th style="width: 50px;">type</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>String</td>
<td>name of template for error report</td>
</tr>
<tr>
<td>loader</td>
<td>Object</td>
<td>contains a load function to load included template</td>
</tr>
<tr>
<td>commands</td>
<td>Object</td>
<td>command definition</td>
</tr>
</tbody>
</table></td>
</tr>
</tbody>
</table>
## Methods
```javascript
String render(data:Object, [option:Object, callback:Function]) // render data
```
<table class="table table-bordered table-striped">
<thead>
<tr>
<th style="width: 100px;">name</th>
<th style="width: 50px;">type</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td>data</td>
<td>Object</td>
<td>data object to be rendered</td>
</tr>
<tr>
<td>option</td>
<td>Object</td>
<td>support runtime commands. for example: {commands: {}}</td>
</tr>
<tr>
<td>callback</td>
<td>Function</td>
<td>callback function after render</td>
</tr>
</tbody>
</table>
## Buffer
### Methods
```javascript
Buffer write(data:String)
```
<table class="table table-bordered table-striped">
<thead>
<tr>
<th style="width: 100px;">name</th>
<th style="width: 50px;">type</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td>data</td>
<td>String</td>
<td>string to be written into buffer</td>
</tr>
</table>
```javascript
Buffer writeEscaped(data:String)
```
<table class="table table-bordered table-striped">
<thead>
<tr>
<th style="width: 100px;">name</th>
<th style="width: 50px;">type</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td>data</td>
<td>String</td>
<td>first escape string, then write it into buffer</td>
</tr>
</table>
```javascript
Buffer async(fn:Function) // generate a new buffer as the first parameter of callback
Buffer end() // mark escape of current buffer
Buffer error(reason) // mark error of current render
```
## Scope
### Members
```javascript
parent // parent scope
root // topmost scope
```
### Methods
```javascript
void setParent(scope: Scope)
void setData(data) // set data of current scope
var getData()
void set(name, value) // set kv value of current scope
void get(name)
```
## custom command
### global command
sync inline command
```javascript
XTemplate.addCommand('xInline',function(scope, option){
return option.params[0]+'1';
});
```
use buffer
```javascript
XTemplate.addCommand('xInline',function(scope, option, buffer){
return buffer.write(option.params[0] + 1);
});
```
```
{{xInline(1)}} // => 2
```
sync block command
```javascript
XTemplate.addCommand('xBlock',function(scope, option, buffer){
return option.fn(scope, buffer).write(option.params[0]);
});
```
```
{{#xBlock(1)}}
2
{{/xBlock}}
// => 21
```
async inline command
```javascript
XTemplate.addCommand('xInline',function(scope, option,buffer){
buffer = buffer.async(function(newBuffer){
setTimeout(function(){
newBuffer.write(option.params[0] + 1).end();
},10);
});
return buffer;
});
```
```
{{xInline(1)}} // => 2
```
async block command
```javascript
XTemplate.addCommand('xInline',function(scope, option,buffer){
buffer = buffer.async(function(newBuffer){
setTimeout(function(){
var newScope = xtpl.XTemplate.Scope({ret:2});
newScope.setParent(scope);
option.fn(newScope, newBuffer);
},10);
});
buffer.write(option.params[0]);
return buffer;
});
```
```
{{#xBlock(1)}}
{{ret}}
{{/xBlock}}
// => 21
```
## loader
a object which contains a load function and passed to XTemplate config
```javascript
void load(params:Object, callback:Function)
```
params detail:
<table class="table table-bordered table-striped">
<thead>
<tr>
<th style="width: 100px;">name</th>
<th style="width: 50px;">type</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>String</td>
<td>included template name</td>
</tr>
<tr>
<td>root</td>
<td>XTemplate</td>
<td>xtemplate instance</td>
</tr>
</table>
for example, XTemplate load precompiled template by require from modulex:
```javascript
var loader = {
cache: {},
load: function (params, callback) {
var name = params.name;
var cache = this.cache;
if (cache[name]) {
return callback(undefined, cache[name]);
}
require([name], {
success: function (tpl) {
cache[name] = tpl;
callback(undefined, tpl);
},
error: function () {
var error = 'template "' + params.name + '" does not exist';
util.log(error, 'error');
callback(error);
}
});
}
};
```
## compiler
XTemplate.Compiler
### Methods
#### compile
```
Object compile(content, name): get compiled function of template whose content is content and name is name
```
#### parse
```
Object parse(content, name): get compiled ast of template whose content is content and name is name
```
#### compileToStr
```
String compileToStr(param:Object): get function string of template whose content is content and name is name
```
param 包含:
<table class="table table-bordered table-striped">
<thead>
<tr>
<th style="width: 100px;">name</th>
<th style="width: 50px;">type</th>
<th style="width: 50px;">default</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>String</td>
<td></td>
<td>name of template</td>
</tr>
<tr>
<td>content</td>
<td>String</td>
<td></td>
<td>content of template</td>
</tr>
<tr>
<td>isModule</td>
<td>Boolean</td>
<td>false</td>
<td>whether generate module require</td>
</tr>
</tbody>
</table>