https://github.com/munawwar/htmlizer
Knockout Templates for Node.js
https://github.com/munawwar/htmlizer
knockoutjs nodejs template-language
Last synced: 6 months ago
JSON representation
Knockout Templates for Node.js
- Host: GitHub
- URL: https://github.com/munawwar/htmlizer
- Owner: Munawwar
- License: mit
- Created: 2014-03-11T20:08:32.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2016-10-24T07:27:07.000Z (almost 9 years ago)
- Last Synced: 2025-04-01T19:09:52.387Z (6 months ago)
- Topics: knockoutjs, nodejs, template-language
- Language: JavaScript
- Homepage:
- Size: 188 KB
- Stars: 9
- Watchers: 4
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: Changelog.txt
- License: LICENSE
Awesome Lists containing this project
README
Htmlizer
========
Generate HTML with templates that are valid HTML.
`npm install htmlizer`
### Why?
Most templating languages doesn't ensure that the templates are valid HTML. Templates needs to be parsable for build tools like assetgraph-builder to able to 1. find assets (like images) for optimization 2. Translate text with their [data-i18n](https://github.com/assetgraph/assetgraph-builder#html-i18n-syntax) syntax.
For example consider this Mustache template: `
`.
This looks sane, but is unfortunately not parsable by most HTML parsers.
Here is another example: `
`. Even though this is parsable, the text inside the style attribute is not valid CSS syntax and some parsers or server-side DOM libraries (used within build tools) could throw errors.
### How?
The solution here is to use template syntax similar to KnockoutJS (in fact supports a subset of Knockout bindings).
Hence other use cases include, partially rendering a KO web page/app on the server-side for SEO purposes.
## What's new in v2
### Performance improvement
With v2, to speed up performance on nodejs, jsdom as a dependency has been removed and htmlizer instead compiles templates into JS functions to generate the output. v2 only supports server-side rendering (unlike v1).
The following are some of the implications due to this change:
1. toDocumentFragment() method has been removed.
2. $element KO binding context cannot be used anymore.
3. template binding interface has changed.
Usage
-----
Render template as HTML string:
```
(new Htmlizer('')).toString(dataObject);
```
Template syntax
-----
Syntax is similar to KnockoutJS (in fact supports a subset of Knockout bindings).
#### *text* binding:
```
Template:
Data: {mytext: 'test'}
Output: test
```
#### *attr* binding:
```
Template:
Data: {mytext: 'test', cls: 'btn btn-default'}
Output: test
```
#### *if* binding:
```
Template:
This message won't be shown.
Data: {show: false}
Output:
```
#### Containerless *if* binding:
```
Template:
No results to display.
Data: {count: 0}
Output:
No results to display.
```
Note: You can use either "ko if:" or "hz if:" to begin an *if* statement. And you may either use "/ko" or "/hz" to end an *if* statement.
#### Containerless *text* binding:
```
Template:
Data: {msg: 'Hello'}
Output:
Hello
```
#### *foreach* binding:
```
Template:
Data:
{
items: ['item 1', 'item 2', 'item 3']
}
Output:
item 1
item 2
item 3
```
#### Containerless *foreach* binding:
```
Template:
Data:
{
items: [{name: 'item 1'}, {name: 'item 2'}, {name: 'item 3'}]
}
Output:
item 1
item 2
item 3
```
#### *html* binding:
```
Template:
Data: {message: 'This is a serious message'}
Output:
This is a serious message
```
#### *css* binding:
```
Template:
Data: {isWarning: true}
Output:
```
#### *style* binding:
```
Template:
Data: {bold: false}
Output:
```
#### *with* binding:
```
Template:
Data: {obj: {val: 10}}
Output:
10
```
#### Containerless *with* binding:
```
Template:
Data: {obj: {val: 10}}
Output: 10
```
#### *template* binding:
Works mostly like KO 3.0 - [documentation](http://knockoutjs.com/documentation/template-binding.html).
Supports the following properties: name, data, if, foreach and as.
```
Template:
subtemplate.html:
Credits:
Data:
{
buyer: {
name: 'Franklin',
credits: 250
}
}
Output:
Credits: 250
Credits: 250
```
To make template work one must add the sub-templates to config as follows.
```
var subtpl = require('fs').readFileSync('subtemplate.html').toString(), //load the file with the sub-templates.
cfg = {
templates: {
"person-template": subtpl
}
},
output = (new Htmlizer('', cfg).toString(dataObject);
```
#### Binding Contexts
Supports all but $element binding contexts documented for KO 3.0 [here](http://knockoutjs.com/documentation/binding-context.html).
```
Template:
Data:
{
items: [{
name: 'item1',
subItems: [{
name: 'subitem1'
}]
}]
}
Output:
item1
item1
0
subitem1
subitem1
true
```
Avoiding conflict with KO
-----
Use case: If you intend to do a partial render with Htmlizer on the server side and the rest with KO on the client side, then you will need to seperate concerns (i.e. avoid conflicts with KO).
To avoid conflict with KnockoutJS, set noConflict config to true:
```
var template = new Htmlizer('', {noConflict: true});
```
By default noConflict is assumed false. With noConflict = true, there are two main differences:
- Bindings must be placed within data-htmlizer attribute.
- Containerless statements with "ko" prefix will be ignored. Use "hz" prefix if you want Htmlizer to process it.
Keep KO bindings
-----
For certain use cases (like for SEO purpose without user agent sniffing), one would like to keep the bindings with the rendered output, so that KO on the client side can rewrite them. To keep KO bindings, set keepKOBindings config to true:
```
var template = new Htmlizer('', {keepKOBindings: true});
```