Wondering what‚Äôs next for npm?Check out our public roadmap! ¬Ľ

    ng-template
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0¬†‚Äʬ†Public¬†‚Äʬ†Published

    ngTemplate 1.0

    NPM

    Build Status

    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.

    Motivation

    • Progressive enhancement friendly: Server-side generated HTML can be fully ready for presentation. During ngTemplate synchronization 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: ngTemplate modifies 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-for and 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)

    How does it work?

    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 );

    Live Demo

    ngTemplate Demo: Hero

    Installing

    You can get ngTemplate via npm.

    npm i --save ng-template
    

    Accessing module

    TypeScript

    import { NgTemplate } from "ng-template";
    const template = new NgTemplate( node );

    CommonJS

    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" ]
    });
    

    VanillaJS

    <script src=""./node_modules/ng-template/dist/ngtemplate.glob.min.js"></script>
    var template = new NgTemplate( node );

    API

    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 details

    where:

    • 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 );

    Options

    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

    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 element

    We 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 element

    Expressions 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 of eval() and therefore the process takes much less time and resources. You can check how the parser treats your expressions by studying content of template.report().tokens array

    ngTemplate Report

    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" ]
     

    Directives

    ngText

    We use ngText to modify element's textNode

    Syntax

    <el data-ng-text="expression => text:string|number" />
    

    Examples

    (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>&lt;button&gt;</i>

    ngProp

    We use ngProp to modify element's properties

    Syntax

    <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="..." />
    

    Examples

    (new NgTemplate( document.body , `<button data-ng-prop="'disabled', isDisabled"></button>` ))
      .sync({ isDisabled: true });
     
    console.log( document.body.innerHTML ); // <button disabled=""></button>

    ngAttr

    We use ngAttr to modify element's attributes

    Syntax

    <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="..." />
    

    Examples

    (new NgTemplate( document.body , `<input data-ng-prop="'required', required">` ))
      .sync({ required: true });
     
    console.log( document.body.innerHTML ); // <input required="true">

    ngData

    We use ngData to modify element's dataset

    Syntax

    <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="..." />
    

    Examples

    (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>

    ngClass

    We use ngClass to modify element's classList

    Syntax

    <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="..." />
    

    Examples

    (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>

    ngIf

    We use ngFor to toggle visibility of an element (subtree) within the DOM

    Syntax

    <el data-ng-if="expression => condition:boolean" />
    

    Examples

    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>

    ngFor

    We use ngFor when we need to generate a list of elements (subtrees)

    ngFor treats 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 synchronization ngFor can do it only if a unique row id property provided. Otherwise it updates the list

    Syntax

    <el data-ng-for="let variable of expression => list:any[]" />
    

    Examples

    (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>

    ngSwitch

    We use ngSwitch when we need to display on element (subtree) of a set of available options.

    Syntax

    <el data-ng-switch="expression => variable:string|number">
      <el data-ng-switch-case="expression => value:string|number" />
      <el data-ng-switch-default />
    </el>
    

    Examples

    (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>

    ngEl

    We use ngEl to modify element properties

    ‚ĚóÔłŹ NOTE: Using ngEl is rather discouraging as it cannot be cached and every model sync will cause the DOM modification even if the expression of ngEl wasn't changed

    Syntax

    <el data-ng-el="expression => eval:void" />
    

    Examples

    (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>

    Contributing

    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.

    How to build

    This source code is written in TypeScript. In order to build the app simply run tsc in the root directory

    How to test

    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

    Analytics

    Install

    npm i ng-template

    DownloadsWeekly Downloads

    62

    Version

    1.0.0

    License

    none

    Last publish

    Collaborators

    • avatar