Monster Templating

Welcome to the Monster Templating Guide, where we explore the dynamic and intuitive DOM-based templating system designed to enhance your HTML with powerful, data-driven components. Monster leverages modern web technologies to offer seamless integration between your data and the document object model (DOM), enabling real-time updates and manipulations with minimal code.

Getting Started

Importing the Updater Class

To utilize Monster's templating features, begin by importing the Updater class from Monster's CDN:

import {Updater} from
                                    '@schukai/monster/source/dom/updater.js';

Preparing the HTML Document

You can integrate Monster's data-binding attributes directly into your HTML or dynamically via JavaScript. Here's how you can dynamically insert an HTML element with Monster's data-binding attribute:

const body =
                                    document.querySelector('body');
                                    const headline = document.createElement('h1');
                                    headline.setAttribute('data-monster-replace', 'path:headline');
                                    body.appendChild(headline);

Alternatively, insert the following tag directly into your HTML document:

<h1
                                    data-monster-replace="path:headline"></h1>

Setting Up Data Binding

Define the data structure you want to bind to your HTML element:

let obj = {
                                    headline: "Go!",
                                    };

Initialize the updater with your document's body (or any parent HTML element) and the data object:

const updater = new Updater(body,
                                    obj);

To monitor and reflect changes in the data structure in real-time, retrieve the proxy object:

const subject =
                                    updater.getSubject();

Activate the updater to start data synchronization:

updater.run();

Demonstrate dynamic data updates with an example:

setTimeout(() => {
                                    subject['headline'] = "Hello!";
                                    }, 1000);

Templating Features

Content Replacement

To replace the content of an HTML element, use the data-monster-replace attribute. This attribute accepts a path to your data or static values, optionally applying transformations:

<div
                                    data-monster-replace="static:HELLO | tolower"></div>

This results in:

<div>hello</div>

Attribute Manipulation

Add or modify HTML attributes through the data-monster-attributes attribute, specifying the attribute name followed by a pipe (|) and the desired operations:

<div data-monster-attributes="id
                                    static:myid, class static:myclass">hello</div>

Element Removal

Use data-monster-remove to permanently remove an HTML element from the document:

<div
                                    data-monster-remove></div>

Dynamic Element Insertion

Insert elements dynamically with data-monster-insert, specifying a template ID and data path:

<ol data-monster-insert="myid
                                    path:a"></ol>

Define a corresponding template:

<template id="myid">
                                    <li data-monster-replace="path:myid | index:id | tostring |
                                    prefix:x"></li>
                                    </template>

Data Binding for Input Elements

Bind input elements to your data structure with data-monster-bind, ensuring real-time synchronization:

<input type="text"
                                    data-monster-bind="path:a.b">

Specify the data type with data-monster-bind-type for accurate data representation:

<input type="number"
                                    data-monster-bind="path:a.b"
                                    data-monster-bind-type="number">

Enhanced Data Binding

The data-monster-bind attribute allows for two-way data binding between HTML input elements and the JavaScript data model. This powerful feature ensures that changes in the input field automatically update the data model and vice versa, keeping your UI and data model in sync.

Usage Example

Bind an input field to a property in your data object:

<input type="text"
                                    data-monster-bind="path:a.b">

To correctly handle different data types, specify the type of data with the data-monster-bind-type attribute:

<input type="number"
                                    data-monster-bind="path:a.b"
                                    data-monster-bind-type="number">

Attribute Summary Table

Attribute	Description	Example
`data-monster-replace`	Replaces the content of an element with the specified data path or static value.	`<div data-monster-replace="path:headline"></div>`
`data-monster-attributes`	Adds or modifies attributes of an element based on specified data paths or static values.	`<div data-monster-attributes="id static:myid"></div>`
`data-monster-remove`	Removes an element from the DOM.	`<div data-monster-remove></div>`
`data-monster-insert`	Dynamically inserts elements based on a template and data path.	`<ol data-monster-insert="myid path:a"></ol>`
`data-monster-bind`	Binds the value of an input field to a data structure, enabling two-way data binding.	`<input type="text" data-monster-bind="path:a.b">`
`data-monster-bind-type`	Specifies the type of data bound to an input field (e.g., number, boolean).	`<input type="number" data-monster-bind="path:a.b" data-monster-bind-type="number">`

Detailed Explanation of Data Types

When binding data to input elements using data-monster-bind, it's crucial to specify the type of data being bound. This ensures that the data is correctly interpreted and manipulated within your application. The data-monster-bind-type attribute supports several data types, each with specific behavior and formatting requirements.

Supported Data Types

Type	Alias	Description
`number`	`int`, `float`, `integer`	Binds numeric values, supporting both integers and floating-point numbers.
`boolean`	`bool`, `checkbox`	Binds boolean values, useful for checkboxes and toggle switches.
`array`	`list`	Interprets a comma-separated string as an array, binding list-like data.
`object`	`json`	Binds a JSON string, allowing complex data structures to be manipulated.

Usage Examples

To bind a numeric value:

<input type="number"
                                    data-monster-bind="path:a.b"
                                    data-monster-bind-type="number">

For a boolean value, particularly useful with checkboxes:

<input type="checkbox"
                                    data-monster-bind="path:a.b"
                                    data-monster-bind-type="boolean">

Binding an array (list) from a comma-separated input:

<input type="text"
                                    data-monster-bind="path:a.b"
                                    data-monster-bind-type="array">

Binding a JSON object:

<input type="text"
                                    data-monster-bind="path:a.b"
                                    data-monster-bind-type="object">

The current width of the area is too small to display the content correctly.