ktl
v0.7.0
Published
Koder's Template Language
Downloads
21
Readme
Koder's Template Language
KTL is a parser factory.
String templating system inspired by doT. It parses template string into javascript function, which in turn can be called with data to return parsed string.
It returns verbatim string (no escaping, etc) makin it useful for generation of configuration files.
It should be augmented with HTML escaper when using on web. Escaping is not implemented by design.
Usage
var output = ktl(template)(data,[sanitizer]);
Supported tags:
Evaluation
All values support complete JavaScript notation. You can freely use operators, methods, global scope objects (ie. Math), etc.
|Tag | Meaning
|---------------------------|--------------------------------------------------------------
|{{ prop }}
| Selected property of object passed to parser
|{{ prop.sub }}
| Subproperties can be accessed with dot notation
|{{ method() }}
| Methods can be called
|{{ value.toFixed(2) }}
| Methods of properties can also be called
|{{ prop ? prop : '-' }}
| All operators are available (in this case: default to '-'
)
|{{ _ }}
| Verbatim object passed to parser, cast to string. Useful in iterations.
|{{ _.toFixed(4) }}
| Methods can also be called on verbatim objects
Iteration
Iteration starts with {{# <array> }}
and ends with {{#}}
. Iterations can be nested. String
between {{# <array> }}
and {{#}}
is treated as new template. Verbatim evaluation ({{ _ }}
) is
useful for arrays of primitives. $
is available as index inside iteration.
|Tag | Meaning
|---------------------------|--------------------------------------------------------------
|{{# array }}
| Iterate over array passed as {array:[]}
to parser
|{{# _ }}
| Verbatim iteration (when passing []
to parser)
Condition
Condition starts with {{? condition }}
and ends with {{?}}
with an optional else {{:}}
.
|Tag | Meaning
|-------------------------------------|--------------------------------------------------------------
|{{? bool }} true {{?}}
| Simple condition
|{{? bool }} true {{:}} false {{?}}
| Condition with else
Sanitizing output
If parser built with KTL is called with function as last argument, it will use this function to sanitize all evaluations. Sanitizer is a function that takes a data value and returns sanitized string.
This feature can be used to use KTL as HTML parser.
Examples:
Template:
Hi {{ name }}! You have {{ messages.length || 'no' }} new messages.
{{# messages }}
{{ title.toUppercase() }}: from {{ from }}
{{#}}
Data:
{
"name":"koder",
"messages": [
{ "title": "message 1", "from": "koder" },
{ "title": "message 2", "from": "dekoder" }
]
}
Output
Hi koder! You have 2 new messages.
MESSAGE 1: from koder
MESSAGE 2: from dekoder
Why KTL?
Most templating languages are web-centric. I required a templating language which works on strings without assuming what those strings will be used for.
Design choices
- KTL gives you parser for a string, which you can call with an object to get something of it.
- It has no dependencies.
- It does not care what do you use this string for.
- It returns verbatim string if there is no data.
- Template caching is out of it's scope. You can cache parsers if you like.
- Escaping string is also out of it's scope.