ngTemplate is a light-weight DOM-based template engine, inspired by AngularJS.
mustache.js, Handlebars or _.template are all nice and shiny, until it comes to a form.
With every rending these template engines replace the bound DOM subtree
and the state of inputs gets lost.
ngTemplate treats the DOM carefully. It modifies the exact target nodes gracefully
according to the directives and actual state.
- Progressive enhancement friendly: Server-side generated HTML can be fully ready for presentation. During
ngTemplatesynchronization it will be updated according to element directives and a provided state - HTML compliant:
data-*- directives instead of foreign concepts such as{{foo}},[hidden],*ngFor,[(ngModel)] - Concern separation: Presentation state logic decoupled from the view
- Performance:
ngTemplatemodifies DOM nodes by state diff; it touches the DOM only when it's necessary - Easy to catch up: Familiar for Angular folks directives such as
data-ng-if,data-ng-switch,data-ng-forand a few extra intuitive e.g.data-ng-text,data-ng-class - Really small library: minimized gziped size is 4K
- Definitely Typed: IDE checks on the fly if you violate any of declared interfaces (if not the compiler does)
Templates are written with HTML that contains ngTemplate-specific data attributes (data-ng-*):
<form id="heroForm" novalidate>
<div class="form-group">
<label for="name">Name</label>
<input id="name" type="text" class="form-control" required >
<div class="alert alert-danger" data-ng-if="!name.valid">
Name is required
</div>
</div>
<div class="form-group">
<label for="power">Hero Power</label>
<select id="power" class="form-control" required>
<option data-ng-for="let p of powers" data-ng-text="p" >Nothing here</option>
</select>
<div class="alert alert-danger" data-ng-if="!power.valid">
Power is required
</div>
</div>
<button type="submit" class="btn btn-default" data-ng-prop="'disabled', !form.valid">Submit</button>
</form>ngTemplate synchronizes the template with the passed state. Let's say we have the template HTML within a DOM element,
so we initialize the template like let template = new NgTemplate( el );. Alternatively we can populate
the bounding element with the template from the passed string: let template = new NgTemplate( el, '<i data-ng-if="foo">Hello!</i>' );
As soon as we have template object we can sync it to a specified scope. E.g. template.sync({ foo: true }); makes
variable foo available for template expressions, template.sync({ foo: { bar: true }}); gets accessable as foo.bar
import { NgTemplate } from "ng-template";
let el = document.querySelector( "#heroForm" ),
elName = document.querySelector( "#name" ),
elPower = document.querySelector( "#power" );
// Bind the template
let template = new NgTemplate( el );
// Set the scope (view state)
let scope = {
powers: [ "-", "Really Smart", "Super Flexible",
"Super Hot", "Weather Changer" ],
power: {
valid: true
},
name: {
valid: true
},
form: {
valid: false
}
};
// Sync to the scope
template.sync( scope );You can get ngTemplate via npm.
npm i --save ng-template
import { NgTemplate } from "ng-template";
const template = new NgTemplate( node );var NgTemplate = require( "ng-template" ).NgTemplate,
template = new NgTemplate( node );In order to adapt your source for browser, you can either browserfy or load your modules with SystemJS
System.config({
paths: {
"*": "node_modules/*"
},
packageConfigPaths: [ "./node_modules/*/package.json" ]
});
<script src=""./node_modules/ng-template/dist/ngtemplate.glob.min.js"></script>var template = new NgTemplate( node );import { NgTemplate } from "ng-template";
let template = new NgTemplate( el, tpl ); // compile template
template.sync( scope ); // render on the first run and after synchronize it with the scope
// optional
console.log( template.report() ); // find the synchronization detailswhere:
- el - a DOM element we bind to
- tpl - OPTIONAL: template code that will be injected into
el - scope - an object literal (template scope) whose members form the scope for template expressions
Also can be instantiated via the factory:
NgTemplate.factory( el, tpl )
.sync( scope );You can define though the constructor options the callbacks willMount and didMount. The first one gets invoked straight before the ngTemplate populates
bounding element's inner HTML from the template string. ngTemplate calls the second callback after that:
import { NgTemplate } from "ng-template";
let template = new NgTemplate( el, tpl, {
willMount: function(){
console.log( "Template is up to initial rendering" );
},
didMount: function(){
console.log( "Template just finished initial rendering" );
}
});Template expressions are being evaluated in the given scope. So we can reference scope variables within template e.g.
data-ng-if="foo" refers to foo variable of the scope and therefore:
template.sync({ foo: true }); // show element
template.sync({ foo: false }); // hide elementWe access scope objects the same way we do it in JavaScript e.g. data-ng-if="foo.bar" refers to foo.bar and can be toggled like this:
template.sync({ foo: { bar: true } }); // show elementExpressions may have mixed scope variables and primitives:
data-ng-if="foo && bar.baz || false"
data-ng-if="foo + 10 > 20"
We can pass rendering helpers (e.g. transformers) with the scope. For example we pass decorator to the directive data-ng-if="decorator(foo)" this way:
{
foo: "foo",
decorator: function( val ){
return "decorated " + val;
}
}
Expressions are evaluated in the context of the target element, so we can access the element with this:
data-ng-if="foo && this.checked"
❗ NOTE: In order to gain better performance keep to primitive expressions especially in cyclic directives e.g.
data-ng-text="foo.bar.baz",data-ng-text="!foo.bar.baz",data-ng-text="'string here'",data-ng-if="foo.bar > baz.quiz",data-ng-text="foo + 10,data-ng-if="true",data-ng-prop="'disabled', true || false",data-ng-data="foo || bar, baz". Such expressions are being evaluated without use ofeval()and therefore the process takes much less time and resources. You can check how the parser treats your expressions by studying content oftemplate.report().tokensarray
You can get template synchronization details like that:
let tpl = new NgTemplate(
document.createElement( "div" ),
"<span data-ng-text=\"foo.bar.baz\"></span>"
);
tpl.sync({});
console.log( tpl.report().errors ); // [ "'foo.bar.baz' is undefined" ]We use ngText to modify element's textNode
<el data-ng-text="expression => text:string|number" />
(new NgTemplate( document.body , `<i data-ng-text="foo"></i>` ))
.sync({ foo: "Foo" });
console.log( document.body.innerHTML ); // <i>Foo</i>HTML gets automatically escaped:
(new NgTemplate( document.body , `<i data-ng-text="foo"></i>` ))
.sync({ foo: "<button>" });
console.log( document.body.innerHTML ); // <i><button></i>We use ngProp to modify element's properties
<el data-ng-prop="expression => propertyName:string, expression => value:boolean|string" />
// Can be applied multiple times on element
<el data-ng-prop-0="..." data-ng-prop-9="..." />
(new NgTemplate( document.body , `<button data-ng-prop="'disabled', isDisabled"></button>` ))
.sync({ isDisabled: true });
console.log( document.body.innerHTML ); // <button disabled=""></button>We use ngAttr to modify element's attributes
<el data-ng-attr="expression => attrName:string, expression => value:boolean|string" />
// Can be applied multiple times on element
<el data-ng-attr-0="..." data-ng-attr-9="..." />
(new NgTemplate( document.body , `<input data-ng-prop="'required', required">` ))
.sync({ required: true });
console.log( document.body.innerHTML ); // <input required="true">We use ngData to modify element's dataset
<el data-ng-data="expression => datasetKey:string, expression => datasetValue:string" />
// Can be applied multiple times on element
<el data-ng-data-0="..." data-ng-data-9="..." />
(new NgTemplate( document.body , `<div data-ng-data="'dateOfBirth', value"></div>` ))
.sync({ value: "1960-10-03" });
console.log( document.body.innerHTML ); // <div data-date-of-birth="1960-10-03"></div>We use ngClass to modify element's classList
<el data-ng-class="expression => className:string, expression => toggle:boolean" />
// Can be applied multiple times on element
<el data-ng-class-0="..." data-ng-class-9="..." />
(new NgTemplate( document.body , `<i data-ng-class="'is-hidden', isHidden"></i>` ))
.sync({ isHidden: true });
console.log( document.body.innerHTML ); // <i class="is-hidden"></i>or
(new NgTemplate( document.body , `<i data-ng-class="className, isHidden"></i>` ))
.sync({ isHidden: true, className: "is-hidden" });
console.log( document.body.innerHTML ); // <i class="is-hidden"></i>We use ngFor to toggle visibility of an element (subtree) within the DOM
<el data-ng-if="expression => condition:boolean" />
let template = new NgTemplate( document.body , `<i data-ng-if="toggle">Hello!</i>` );
template.sync({ toggle: false });
console.log( document.body.innerHTML ); // <ng style="display: none; "></ng>
template.sync({ toggle: true });
console.log( document.body.innerHTML ); // <i>Hello!</i>We use ngFor when we need to generate a list of elements (subtrees)
ngFortreats the generated list gracefully. It tries to maintain the nodes once appended to the DOM on list data change. However of removing rows from the list during synchronizationngForcan do it only if a unique rowidproperty provided. Otherwise it updates the list
<el data-ng-for="let variable of expression => list:any[]" />
(new NgTemplate( document.body , `<i data-ng-for="let row of rows" data-ng-text="row"></i>` ))
.sync({ rows: [ "foo", "bar" ] });
console.log( document.body.innerHTML ); // <i>foo</i><i>bar</i>We use ngSwitch when we need to display on element (subtree) of a set of available options.
<el data-ng-switch="expression => variable:string|number">
<el data-ng-switch-case="expression => value:string|number" />
<el data-ng-switch-default />
</el>
(new NgTemplate( document.body ,
`<div data-ng-switch="theCase">
<i data-ng-switch-case="1">FOO</i>
<i data-ng-switch-case="2">BAR</i>
</div>` ))
.sync({ theCase: 1 });
console.log( document.body.innerHTML ); // <i>FOO</i>(new NgTemplate( document.body ,
`<div data-ng-switch="theCase">
<i data-ng-switch-case="1">FOO</i>
<i data-ng-switch-case="2">BAR</i>
<i data-ng-switch-case-default>BAZ</i>
</div>` ))
.sync({ theCase: 100 });
console.log( document.body.innerHTML ); // <i>BAZ</i>We use ngEl to modify element properties
❗ NOTE: Using
ngElis rather discouraging as it cannot be cached and every model sync will cause the DOM modification even if the expression ofngElwasn't changed
<el data-ng-el="expression => eval:void" />
(new NgTemplate( document.body , `<i data-ng-el="this.className = class"></i>` ))
.sync({ class: "is-hidden" });
console.log( document.body.innerHTML ); // <i class="is-hidden"></i><i data-ng-el="this.textNode = mymodel.foo"></i>
<i data-ng-el="this.setAttribute( 'name', mymodel.foo )"></i>
<i data-ng-el="this.disabled = state.isVisible"></i>
<i data-ng-el="this.classList.toggle('name', model.foo)"></i>ngTemplate welcomes maintainers. There is plenty of work to do. No big commitment required,
if all you do is review a single Pull Request, you are a maintainer.
This source code is written in TypeScript. In order to build the app simply run tsc in the root directory
There two options. You can run unit-tests in the console:
npm run test
or you can fire up tests/index.html in a browser