Getting Started  •  Options  •  API  •  Benchmark  •  Template Compiler  •  Server-Side-Rendering  •  Express Render Engine  •  Reactive  •  Hydration  •  Web Components (Shadow DOM)  •  Changelog

When you are coming from any previous version: Migration Guide 0.8.x

Benchmark:

• Stress Test Benchmark
• https://krausest.github.io/js-framework-benchmark/current.html

Demo:

• TodoMVC App: Project / Source / Demo

Mikado was getting so much positive feedback and also feature requests. Help keeping Mikado active by a personal donation.

Rendering has great impact on application performance, especially on mobile devices. Mikado takes templating performance to a new level and provides you keyed, non-keyed recycling and also reactive paradigm switchable out of the box. Additionally, Mikado provides a server-side-rendering approach on a top-notch performance level along full support for hydration to inject templates progressively within the client's runtime. Server and client are sharing the same template definitions simply written in HTML-like markup. The server side approach will also come with the fastest middleware render engine for Express you can get today. Packed with a smart routing feature for event delegation and full support for web components by using the Shadow DOM, Mikado gives you everything you'll need to build realtime applications on a cutting edge performance level.

1. Get Latest
2. Feature Comparison: Mikado Light
3. Benchmark Ranking (Rendering Performance)
4. API Overview
5. Mikado Options
6. Getting Started (Basic Example)
7. Rules and Conventions
8. Advanced Example
9. Template Compiler
   • Reserved Keywords
   • Compiler Flags
   • Auto Naming
   • Prebuilt Cache
   • Watcher (Auto-Compile)
   • Runtime Compiler
10. Template Expressions
    • Value Insertion
    • JS Inline Code
    • Truthy Values
    • Escape Values (SSR)
    • HTML Contents
    • Sanitizer
    • Reactive Bindings
11. Routing & Event Delegation
    • Event Bubbling
    • Event Cache
    • Explicit Register Event Delegation
    • Control Native Events
    • Dispatch Routes
12. Recycling Modes:
    • Non-Keyed Recycling
    • Keyed Recycling
13. Views:
    • Create Views
    • Mount Views
    • Destroy Views
    • Render Templates
    • Create Components
    • Modify Views
    • Common View Helpers
    • Manipulate Views
14. DOM State Caching
    • State Caching Concept
    • DOM Cache Helpers
15. View State
16. Custom Callbacks
17. Static Templates
    • Once (One-time rendering)
18. Server-Side Rendering (SSR)
    • SSR-exclusive Mode
19. Express Render Engine
    • Custom Options
    • Render Views
20. Template Features:
    • Template Expressions
    • Includes
    • Loop Partials
    • Inline Loops
    • Conditional Template Structures
21. Reactive Features:
    • Reactive Properties (Proxy)
    • Reactive Array (Virtual NodeList)
    • Limitations
    • Strict-Proxy Mode
    • Transactions
22. Template Pools
23. Hydration
24. Web Components (Shadow DOM)
25. Full Template Example
26. Best Practices
27. Concept of Shared Components
28. Custom Builds
    • Supported Build Flags

Do not use the "src" folder of this repo. It isn't meant to be used directly, instead it needs compilation. You can easily perform a custom build, but don't use the source folder for production. You will need at least any kind of compiler which resolve the compiler flags within the code. The "dist" folder is containing every version which you probably need including unminified modules.

All debug versions are providing debug information through the console and gives you helpful advices on certain situations.

Bundles export all their features as static functions to the public class namespace "Mikado" e.g. Mikado.register().

The abbreviations used at the end of the filenames indicates:

• bundle All features included, Mikado is available on window.Mikado
• light Only basic features are included, Mikado is available on window.Mikado
• es5 bundle has support for EcmaScript5, Mikado is available on window.Mikado
• module bundle is a Javascript module, Mikado is available by import Mikado from "./mikado.bundle.module.min.js"
• min bundle is minified
• debug bundle has enabled debug mode (only for development purposes, do not use for production)

When using modules you can choose from 2 variants: mikado.xxx.module.min.js has all features bundled on the public class namespace e.g. Mikado.register(), whereas the folder /dist/module/ export most of the features as functions which needs to be imported explicitly by import { register } from "./dist/module/mikado.js".

Also, for each variant there exist:

1. A debug version for the development
2. A pre-compiled minified version for production

Load the bundle by a script tag:

<script src="dist/mikado.bundle.min.js"></script>
<script>
  // ... access Mikado
</script>

Install Mikado via NPM:

npm install mikado

The dist folder are located in node_modules/mikado/dist/.

Use the bundled version exported as a module:

<script type="module">
    import Mikado from "./dist/mikado.bundle.module.min.js";
    // bundled access by e.g. Mikado.register()
</script>

Also, pre-compiled non-bundled production-ready modules are located in dist/module-min/.

<script type="module">
    import Mikado, { register } from "./dist/module-min/mikado.js";
    // bundled access by Mikado.register isn't available
    // requires direct access by e.g. register()
</script>

You can also load modules via CDN:

<script type="module">
    import Mikado from "https://unpkg.com/mikado@0.8.404/dist/module/mikado.js";
</script>

Loading modules via CDN commonly expects to build/bundle your app properly before distribution. Do not load them via CDN in production.

Run the benchmark (non-keyed recycle):
https://raw.githack.com/nextapps-de/mikado/bench/

Run the benchmark (keyed recycle):
https://raw.githack.com/nextapps-de/mikado/bench/#keyed

Run the benchmark (internal/data-driven):
https://raw.githack.com/nextapps-de/mikado/bench/#internal

The values represent operations per second, each benchmark task has to process a data array of 100 items. Higher values are better, except for memory (the sum of allocated memory during the whole test).

The index is a statistic rank having a maximum possible value of 100, this requires a library to be the best in each test category (regardless how much better). The score value is based on median factorization, here a score of 100 represents the statistical midfield.

Most of these methods are optional, you can just use view.render(data) to apply all changes automatically.

Constructor:

• new Mikado(template, <options>) : view
• new Mikado.Array(array) : observable

Instance properties:

• view.name readonly
• view.root readonly
• view.length readonly
• view.state readonly

Static properties (not included in mikado.light.js):

• Mikado.eventCache : boolean
• Mikado.eventBubble : boolean

Static methods:

• Mikado.once(root, template, <data>, <state>, <callback>)
• Mikado.register(template, <options>)
• Mikado.unregister(template)

Static methods (not included in mikado.light.js):

• Mikado.route(name, function, <options>)
• Mikado.listen(event, <options>)
• Mikado.unlisten(event)
• Mikado.dispatch(route, <target>, <event>)
• Mikado.escape(text) : string
• Mikado.sanitize(text) : string

Instance methods:

• view.mount(root, <hydrate>)
• view.render(<data>, <state>, <callback>)
• view.create(data, <state>, <index>) : node
• view.add(data, <state>, <position>)
• view.append(data, <state>, <position>)
• view.update(node | index, data, <state>)
• view.replace(node | index, data, <state>)
• view.remove(node, <count>)
• view.clear()
• view.node(index) : node
• view.index(node) : number
• view.flush()
• view.destroy()

Instance methods (not included in mikado.light.js):

• view.route(name, function, <options>)
• view.listen(event, <options>)
• view.unlisten(event)
• view.dispatch(name, <target>, <event>)

View manipulation helpers (optional, not included in mikado.light.js):

• view.move(node | index, position)
• view.shift(node | index, offset)
• view.up(node | index)
• view.down(node | index)
• view.first(node | index)
• view.last(node | index)
• view.before(node | index, node | index)
• view.after(node | index, node | index)
• view.swap(node | index, node | index)

Static DOM Cache helpers (optional, not included in mikado.light.js):

• Mikado.setText(node, text)

• Mikado.getText(node) : string

• Mikado.setHtml(node, html)

• Mikado.getHtml(node) : string

• Mikado.setClass(node, [classnames])

• Mikado.getClass(node) : [string]

• Mikado.addClass(node, classname)

• Mikado.addClass(node, [classnames])

• Mikado.hasClass(node, classname) : boolean

• Mikado.removeClass(node, classname)

• Mikado.removeClasses(node, [classnames])

• Mikado.toggleClass(node, classname, <state>)

• Mikado.toggleClasses(node, [classnames], <state>)

• Mikado.toggleClasses(node, {classname: state})

• Mikado.setStyle(node, property, value)

• Mikado.setStyles(node, {property: value})

• Mikado.getStyle(node, property) : string

• Mikado.setCss(node, css)

• Mikado.getCss(node) : string

• Mikado.setAttribute(node, attribute, value)

• Mikado.setAttribute(node, {attribute: value})

• Mikado.getAttribute(node, attribute) : string | null

• Mikado.hasAttribute(node, attribute) : boolean

• Mikado.removeAttribute(node, attribute)

• Mikado.removeAttribute(node, [attributes])

Observable constructor (optional, not included in mikado.light.js):

• new Mikado.Array(<array>) : observable

Observable array-like methods (optional, not included in mikado.light.js):

• observable.length : number
• observable.mount(view)
• observable.concat([object])
• observable.push(object)
• observable.splice : [Object]
• observable.pop : Object
• observable.shift : Object
• observable.unshift(object)
• observable.slice(<index>, <count>)
• observable.set([object])
• observable.sort(fn)
• observable.reverse()
• observable.swap(idx_a, idx_b)
• observable.map(fn)
• observable.filter(fn)
• observable.indexOf(object) : number
• observable.lastIndexOf(object) : number
• observable.includes(object) : boolean
• observable.forEach(fn)
• observable.transaction(fn)

Each Mikado instance, also named includes/partials can have their own options. Except inline partials always inherits the same options from its parent. For this reason you should prefer named includes over inlining in certain situations.

The Mikado Compiler requires Node.js to be installed. This is probably the simplest step in this guide.

Install Mikado from NPM (this will also install the compiler):

npm install mikado

Assume there is an array of data items to render (or just one item as an object):

const data = [{
    username: "User A",
    tweets: ["foo", "bar", "foobar"]
},{
    username: "User B",
    tweets: ["foo", "bar", "foobar"]
},{
    username: "User C",
    tweets: ["foo", "bar", "foobar"]
}];

Accordingly, a template tpl/partial/user.html might look like:

<table>
  <tr>
    <td>User:</td>
    <td>{{ data.username }}</td>
  </tr>
  <tr>
    <td>Tweets:</td>
    <td>{{ data.tweets.length }}</td>
  </tr>
</table>

In your console type this command line:

npx mikado-compile ./tpl/

<script type="module">
    import Mikado from "mikado.bundle.module.min.js";
    import template from "tpl/partial/user.js";
    const view = new Mikado(template, {/* options */});
</script>

<script src="mikado.bundle.min.js"></script>
<script src="tpl/partial/user.es5.js"></script>
<script>
    var view = new Mikado("user/list", {/* options */});
</script>

The name of a template inherits from its corresponding filename starting by the folder you've passed through the --src flag when calling the compiler.

After creation, you need mount the Mikado view instance to an HTML element as a destination for your render tasks:

view.mount(HTMLelement);
view.render(data);

You can also chain methods:

Mikado(template).mount(HTMLelement).render(data);

There is just a single convention you always need to keep in mind:

Every template has to provide one single root element as the outer boundary.

Instead of doing this in a template:

<header>
  <nav></nav>
</header>
<section>
  <p></p>
</section>
<footer>
  <nav></nav>
</footer>

Wrapping everything into a single outer root element by doing this:

<main>
  <header>
    <nav></nav>
  </header>
  <section>
    <p></p>
  </section>
  <footer>
    <nav></nav>
  </footer>
</main>

You can also use a <div> or any other element as a template root (also custom elements). The root element can also hold two special attributes key and cache. We will come later to it.

A bit more complex template:

<section id="{{ data.id }}" class="{{ this.state.theme }}" data-index="{{ index }}">
  {{@ var is_today = data.date === state.today }}
  <div class="{{ data.class }} {{ is_today ? 'on' : 'off' }}">
    <div class="title" style="font-size: 2em">{{ data.title.toUpperCase() }}</div>
    <div class="content {{ index % 2 ? 'odd' : 'even' }}">{{# data.content }}</div>
    <div class="footer">{{ state.parseFooter(data) }}</div>
  </div>
</section>

You can use any Javascript within the {{ ... }} curly bracket notation. The scope is limited by the template, so variables from one template can't be accessed within another template (use state for this purpose).

To pass HTML markup as a string, the curly brackets needs to be followed by # e.g. {{# ... }}. For better performance, relevant tasks avoid passing HTML contents as a string.

To use Javascript outside an element's context you need to prevent concatenation of the returned value. For this purpose, the curly brackets need to be followed by @ e.g. {{@ ... }}.

Within a template there are several reserved keywords you can use as an identifier:

You cannot change the names of those preserved keywords, also make sure you didn't override them.

It is recommended to pass custom functions via the state object (see example above state.parseFooter = function(str){ return str; }). Alternatively you can also nest more complex computations inline as an IIFE and return the result.

<div class="date">{{ 
    (function(){ 
        var date = new Date();
        // perform some code ...
        return date.toLocaleString();
    }())
}}</div>

To finish the example from above you need one single data object or an array of data items:

var data = [{
    "id": "230BA161-675A-2288-3B15-C343DB3A1DFC",
    "date": "2019-01-11",
    "class": "yellow, green",
    "title": "Sed congue, egestas lacinia.",
    "content": "<p>Vivamus non lorem <b>vitae</b> odio sagittis amet ante.</p>",
    "footer": "Pellentesque tincidunt tempus vehicula."
}];

Provide the optional state payload which includes specific values and helper methods used within template expressions:

const state = {
  today: "2019-01-11",
  theme: "custom",
  parseFooter: function(data) {
    return data.footer;
  }
};

Mount the view to a target element as a destination for all the render tasks:

view.mount(HTMLelement);

Render a mounted template:

view.render(data, state);

Render asynchronously automatically by just providing a callback function:

view.render(data, state, function() {
  console.log("finished.");
});

To render asynchronously by using promises you need to set the callback value to true:

// callback "true" will use Promises
view.render(data, state, true).then(function() {
    console.log("finished.");
});

// same, but uses async/await:
await view.render(data, state, true);
console.log("finished.");

When async should be the default strategy for all render tasks then you can also set the async option flag:

const view = new Mikado(template, { async: true });
await view.render(data, state);
console.log("finished.");

Define an HTML-like template and use double curly brackets to markup dynamic expressions which should be calculated and replaced during runtime:

<table>
  <tr>
    <td>User:</td>
    <td>{{ data.username }}</td>
  </tr>
  <tr>
    <td>Tweets:</td>
    <td>{{ data.tweets.length }}</td>
  </tr>
</table>

Save this template e.g. to tpl/partial/user.html

The preserved keyword data is a reference to the passed data item. You can access the whole nested object.

Mikado comes with a builtin template compiler you can simply access by typing npx mikado-compile into your console. The compiler uses a very simple command-line interface (CLI) running on Node.js to perform compilation tasks. The template compiles into a native javascript file which needs to be passed during creation of a Mikado instance. The same markup is also used for the server-side rendering part, so you can share the same template sources for client and server rendering.

Show help to list all available commands:

npx mikado-compile --help

Compile the template through the command line by:

npx mikado-compile tpl/partial/user.html

Basic Notation:

npx mikado-compile source <destination>

When no destination folder was set, the compiled files will be saved to the source folder. After compilation, you will have 3 different files:

1. list.js the template compiled as a ES6 module (which needs to be imported)
2. list.es5.js the template compiled as ES5 compatible Javascript (which automatically register when loaded by script tag)
3. list.html the source template you have implemented (do not delete it)

Extended Notation:

npx mikado-compile --src { source } --dest { destination } --extension html --type module --compact

Compiler Flags:

• --type module, -t module export as javascript modules (recommended)
• --type es5, -t es5 export as ES5-compatible package
• --extension html, --ext html, -e html the file extension which should be compiled
• --inline, -i or --compact, -c switch the build strategy to optimize either the performance (inline) or size (compact)
• --force, -f force overwriting existing files
• --pretty, -p do not minify the compiled result
• --watch, -w start the watcher for automatically compile when files has changed (just for development purposes)

Supported flags as attributes on the template root:

<!-- switch the build strategy to prebuilt enabled cache -->
<table cache="true"></table>

<!-- switch the build strategy to prebuilt disabled cache -->
<table cache="false"></table>

Using the flag attributes are the most performant variants but also cost you some flexibility, because the cache strategy couldn't be changed in runtime, it needs to change in markup before compilation.

There is a new naming system which will apply by default. The name of your html files will be used as unique identifiers of your templates. Because several folders can include same filenames, the template name inherits from the full path you pass in as --src.

Assuming the following file structure:

tpl/view/start.html
tpl/view/user.html
tpl/view/cart.html
tpl/partial/start.html
tpl/partial/user.html
tpl/partial/cart.html

The command should define the path /tpl/ as the source root because it is the most inner folder which covers all files:

npx mikado-compile ./tpl/

The template names then becomes view/start, view/user, view/cart and partial/start, partial/user, partial/cart for the partials. So when including just use this name in your expression <table include="partial/user">

The wrong way is to compile the folder /view/ and /partial/ separately, because their template names will be same.

npx mikado-compile ./tpl/view/
npx mikado-compile ./tpl/partial/

This might also work, but it is better not to do.

The option { cache: true/false } when creating a Mikado instance could be better declared withing templates on their root element, let the compiler produce more optimized code for this strategy.