comps
A Precompile and data-independent template engine for nodejs.
Install
npm install comps --save
Start up
Using with ejs, compile and render before ejs rendering.
var comps = var ejs = /** * Custom method for loading component's template file by id */compsvar tpl = var html = ejs
See example.
Doc
Class Methods
Comps(options)
- Param: options
<String>
, see options - Return:
<String>
Render given template to string directly with options.
create()
Create Comps instance with isolated private variables.
var Comps =
config(name, value)
- Param: name
<String>
- Param: value
Rendering configuration setter. Supporting properties:
- openTag
<String>
Template syntax of open delimiter. Default "{%". - closeTag
<String>
Template syntax of close delimiter.Default: "%}"
tag(name, def)
-
Param: name
<String>
Tag name, using as{% xxtag /%}
or{% xxtag %}{%/ xxtag %}
-
Param: def
<Object>
Tag configuration. Supporting properties:-
scope
<Boolean>
|<Function>
Optional Whether create a child-scope for the tag. -
paired
<Boolean>
Optional Restrains the type of tag. if true, can't not using tag as self-closing. If false, the tag must be self-closing. Otherwise has not constraint. -
created
<Function>
Call when tag is created. -
outer
<Function>
Call when tag is rendered. Must return Array with two items, item1 is the open tag, item2 is the close tag. -
inner
<Function>
Call when tag's child template is rendered. Must return String.
-
Context of defined method:
- $scope
<Object>
Scope of current context, properties will be herited to child-scope. - $el
<Object>
AST node of the tag. - $raw
<String>
Tag's raw content. - $name
<String>
Tag name. - $attributes
<Object>
All attributes of the tag. - $walk
<Function>
AST traverse method, using to continue traverse childNodes of the tag. - $render
<Function>
All attributes of the tag.
compile(tpl)
- Param: tpl
<String>
Compiled template as the same of options.template. - Return:
<Function>
Render method.
Pre-render template and return render method that receive options
as params.
bcompile(options)
- Param: options
<Object>
Template render options, see options - Return:
<Function>
Bigpipe factory function that will return bigpipe instance after calling
Pre-render template and return factory function that will be create a bigpipe
instance after calling.
bigpipe(options)
- Param: options
<Object>
Template render options, see options - Return:
<Object>
Bigpipe instance. See Using Bigpipe
Create a bigpipe
instance directly.
componentLoader(loader)
- Param: loader
<Function>
Custom component template file loader method. loader
function will receive id<String>
as param, id is the component id that given by tag's $id attribute.
Loader should return object as result, and result must contains properties:request
, content
.
Note: Only one loader work, it will overwrite last loader.
fileLoader(loader)
- Param: loader
<Function>
Custom including template file loader method. loader
function will receive request<String>
and context<String>
as params. request is $path attribute and context is the current directory path of the request.
Loader should return object as result, and result must contains properties:request
, content
.
Note: Only one loader work, it will overwrite last loader.
componentTransform(transform)
- Param: transform
<Function>
Add call transform function before component tag rendering. this
of transform point to tag instance and receive component id<String>
as param.
Using Pagelet
Configuration:
var str =
Using pagelet in HTML template:
{% pagelet $id="main" %} {% pagelet $id="content" %} here is content. {% /pagelet %} out side. {% /pagelet %}
Render result:
here is content.
It will be wrapped with a pagelet tag default, set $wrap to false
will disable wrapper.
Using Bigpipe
Create bigpipe instance:
var creator = Compsvar bp =
Using chunk in template:
header-{{title}}{% chunk $id="header" $require="title" /%}...{{list}}...{% chunk $id="list" $require="list" /%}
Listen events and handle data:
bpbp // will emit "header" chunkbp
Using multiple data at once:
bp
Using endChunk() end up dependence waiting of the chunk:
bpbp
Using flush() to check and write chunk when set data directly:
bpdatatitle = ''bpdatalist = bp
End bigpipe
manually, it flush remain chunks immediately but ignore waiting dependences:
bp
Reusable Template
Assume a component template ./index.tpl
as below:
{% pagelet $id="list" %} item {% /pagelet %}
If you need do client-side render and reuse the template in some case, you can use comps-loader .
Note: "comps-loader" is comps's template loader for webpack, and you need do some configuration when use it. See detail
Load template in client-side when using comps-loader:
// load full template filevar tpl = // load pagelet of templatevar pagelet =
Pagelet result =>
item
If you don't like require('!!comps!./index.tpl?pagelet=list')
, you can create an independ file for list template:
./index.tpl
{% include $path="./list.tpl" /%}
./list.tpl
:
item
Load templates:
// load full template filevar tpl = // load list templatevar pagelet =
Options
Options of rendering template with comps(options)
:
template
- Type:
<String>
HTML template for rendering.
pagelet
- Type:
<String>
- Optional
Render those template including in pagelet tag. It compare pagelet
option with pagelet tag's $id
.
See Using pagelet.
chunk
- Type:
<Boolean>
- Optional
Note: Chunk is enable default in
bigpipe
rendering.
If chunk is true, Comps
will render Chunk tag to CHUNK_SPLITER
, such as: <!--{% chunk /%}-->
.
See Using Bigpipe.
context
- Type:
<String>
- Optional
Note: Using with
include
tag.
Specify current directory path of the given template.
Comps Tags
All build-in available tag of comps.
component
Component tag is using to load and handle component template file
Example
{% component $id="header" /%}
It will call componentLoader
to loader component file by id "header".
Tag attributes:
- $id Id name of the component for load component file.
- $tag Specify tag name of component wrapper tag. Optional
- $replace Using component wrapper tag of not, default
false
. Set to "nomerge
" will not copy attributes to template container element, otherwise all attribute from the component tag will copy to template container element and overwrite exist attribute.Optional
Events
-
componentcreated(tagInstance)
-
beforecomponentload(id, tagInstance)
-
componentloaded(id, tagInstance, result)
After load, will get request/context of the component in "tagInstance", changing will change render result.
Insertion point
{% component $id="header" /%}Inner Content{% /component %}
Using $content
:
{%> $content /%}
Will render to:
Inner Content
noti: Comps's tags of
Inner Content
will be rendered by outer component scope
pagelet
Pagelet tag is using to render template only that included in pagelet if pagelet
option is given.
Example:
{% pagelet $id="header" $wrap=false %} {%/ pagelet %}
If pagelet of rendering options is "header", it will render the template included in pagelet tag only.
Attributes:
- $id Id name of the pagelet for matching.
- $tag Specify tag name of pagelet wrapper tag. Optional
- $wrap Using pagelet wrapper tag of not, default
false
. Optional
include
Inline another HTML template file into current template.
Example:
{% include $path="./header.tpl" /%}
Attributes:
- $path File path, can be relative or absolute.
Events
-
beforefileload(request, context, tagInstance)
-
fileloaded(result, tagInstance)
After load, will get request/context of the file in "tagInstance", changing will change render result.
Passing data
{% include $path="./header.tpl" $data="{title: 'Comps passing data from include'}"/%}
Using in header.tpl
{%> title /%}
Will render to:
Comps passing data from include
chunk
Bigpipe chunk split tag, and declare data dependences of above chunk.
Example:
......{% chunk $require="title,name" /%}......
chunk
event will be emitted if require dependences are done.
Attributes:
- $require Require dependences, multiple keys splited by "
,
" .
output(>)
Execute expression and output data that given by component.
Declare data in component tag:
{% component $id="main" $data="{ title: 'Output ag', content: 'Data from components' }" /%}
Templte of "main"
component:
{%> 'Title is: ' + title /%} {%> 'Content is: ' + content /%}
Render result:
Title is: Output tag Content is: Data from components
Build in properties and methods:
- $exist <
Function
> checkout the property in current scope exist or not - $get <
Function
> get property value from current scope - $data <
Object
> expose scope's data object
if(?)
Branch logic, it will render contents if condition's value is truly.
{% component $id="main" $data="{ isShowText: true }"/%}
Templte of "main"
component:
{%? isShowText%} Hello world {%/?%}
Render result:
Hello world
Has same build in properties and methods of output(>)
repeat
Create data scope and declare variables.
{% repeat $items="['Comps','Repeat']" $as="item" $index="index" %} Index: {%> index /%}, Item: {%> item /%}{% /data %}
Render result:
Index: 0, Item: CompsIndex: 1, Item: Reapt
data
Create data scope and declare variables.
{% data name="send" %} My name: {%> name /%}{% /data %}
Render result:
My name: send