https://github.com/adzerk/micro-html-template
Template compiler for nodejs
https://github.com/adzerk/micro-html-template
delivery
Last synced: about 2 months ago
JSON representation
Template compiler for nodejs
- Host: GitHub
- URL: https://github.com/adzerk/micro-html-template
- Owner: adzerk
- License: other
- Created: 2017-12-15T16:16:19.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2018-01-19T13:34:04.000Z (over 8 years ago)
- Last Synced: 2025-12-31T14:43:44.909Z (6 months ago)
- Topics: delivery
- Language: CoffeeScript
- Homepage:
- Size: 39.1 KB
- Stars: 0
- Watchers: 24
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# micro-html-template
Template system based roughly on [Jinja2][jinja], designed with a focus on
security, simplicity, rendering speed, and minimal clientside footprint.
Features:
* **Small feature set** — focused on simple value replacement and filters.
* **Small runtime** — the JavaScript needed to render compiled templates
in the client is about 1.1KB, uncompressed.
* **Small precompiled size** — compiled templates are approximately the
same size as the templates themselves.
* **Contextual escaping** — [anti-XSS escaping policies][owasp-xss] are
applied automatically based on the HTML context.
Non-Features:
* **Compiling templates in the client** — templates must be precompiled
in nodejs.
* **Complex template programming** — no support for loops, conditionals,
tags, inheritance, etc.
* **Protection against malicious templates** — it is assumed that templates
are created by trusted users only.
## Usage
Compile and render a template in nodejs:
```javascript
// Compile
var compile = require('micro-html-template').compile;
var precompiled = compile("
");
// Render
var render = require('micro-html-template-runtime').render;
var env = {user: {name: 'Jar Jar B.'}};
var htmlContent = render(precompiled, env);
```
Render the template in the client:
```html
var precompiled = '...'; // precompiled template string from nodejs
var env = {user: {name: 'Jar Jar B.'}};
var htmlContent = microHtmlTemplate.render(precompiled, env);
document.getElementById('template1').innerHTML = htmlContent;
```
The result:
```html
```
See the [tests][tests] for more examples.
## Templates
This libarary is designed for applications where templates are created only by
trusted users, but data used to render the templates is untrusted. Template
data will be automatically protected against XSS by a combination of HTML and
URI component escaping, depending on the context.
**Templates must be valid HTML** — macros may only appear in:
* text nodes
* quoted attribute values
**Macros in unsafe contexts are ignored** — macros may not appear in:
* `` tags
* `<style>` tags
* `style` attribute values
* `on*` event attribute values
Ok:
```jinja
<!-- Text nodes are safe contexts (except in 'style' and 'script' tags). -->
<div>Hello, {{user.name}}!</div>
```
```jinja
<!-- Quoted attribute values are safe contexts (except for 'style' and 'on*'). -->
<img height='{{height}}px'>
```
Unsafe:
```jinja
<!-- Template is not valid HTML. (Behavior is undefined.) -->
<{{tag.name}} src='http://example.com'>
```
```jinja
<!-- Macro in script tag (passed through verbatim). -->
<script>var x = {{foo.x}};
```
```jinja
html {background:{{colors.foo}};}
```
```jinja
hello world
```
```jinja
hello world
```
## Contextual Escaping
The results of all macro replacements are automatically HTML escaped. However,
certain attributes are interpreted as URIs by the browser (the `src` attribute
of an ``, for example). Macro replacements in these attributes are URI
encoded (eg. `encodeURIComponent()`) and then HTML escaped.
```jinja
hello {{user.name}}
```
```jinja
![]()
```
```jinja
```
## Raw Mode
Automatic contextual escaping can be disabled for individual macros: see [Filters](#filters) below.
## Values
The values used in macro expansion are provided as literals or via the `env`
object (passed as an argument to `render`).
```jinja
- i = {{"√-͞1"}}
- ? = {{42}}
- π = {{3.14}}
- ħ = {{6.58e-16}}
```
```jinja
```
```jinja
```
```jinja
```
```jinja
```
```jinja
```
## Filters
Filters are functions that are applied to the replacement text. Filters are
expressed as a pipeline:
```jinja
```
Filters beginning with a `.` character denote method invocation:
```jinja
```
Filters and methods may take arguments:
```jinja
```
The following built-in filters are included:
* `id` — The identity filter, does nothing.
* `uri` — Escapes input for URI component context.
* `html` — Escapes input for HTML context.
* `raw` — Applied at the end of the pipeline this filter disables auto-escaping.
Note that the `uri` and `html` filters are automatically applied as needed to
prevent XSS. However, it may sometimes make sense to use them in macros, for
instance to escape URI components in an attribute that is not automatically
interpreted by the browser as a URI type:
```jinja
```
Or if you need to double-escape a URI component for some reason:
```jinja
Query
```
Or when using the `raw` filter on trusted data:
```jinja
```
## Custom Filters
Filters can be added to the runtime in nodejs:
```javascript
runtime = require('micro-html-template-runtime');
runtime.filters.uppercase = function(val) {
return val.toUpperCase();
};
```
or in the client:
```html
microHtmlTemplate.filters.uppercase = function(val) {
return val.toUpperCase();
};
```
Filters may accept additional arguments:
```html
microHtmlTemplate.filters.wrap = function(val, start, end) {
return start + val + end;
};
```
Pass the additional arguments to the filter in the template:
```jinja
```
## Escaping Macro Delimiters
To include the macro start delimiter `{{` itself in a template it must be
escaped by preceeding it with another start delimiter, like this: `{{{{`.
```jinja
```
```jinja
```
## Hacking
```bash
# Install dependencies.
npm install
```
```bash
# Compile parser, minify runtime, etc.
make
```
```bash
# Run tests.
make test
```
## License
Copyright © 2017 Adzerk, Inc.
Distributed under the [Apache License, Version 2.0][apache].
[apache]: https://www.apache.org/licenses/LICENSE-2.0
[jinja]: http://jinja.pocoo.org/docs/2.10/
[tests]: test/micro-html-template.tests.coffee
[owasp-xss]: https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet