jQuery DNA Template

Incredibly simple and yet powerful non-destructive javascript templating system. Allows you to effortlessly build and efficiently manage UI code (or let web designers to do that without breaking your UI-building javascript code).

Table of Contents

Features
Quick Introduction
Interactive Examples
Syntax
- Javacript
- HTML
More

Features

Supports nested templates with for-each-like behavior (recursive templates supported)
You can apply template multiple times to the same element to update UI with changed values
Support for adding/removing classes conditionaly (e.g. add this class if value is true )
Support for conditional attributes (e.g. check the check-box if value is true)
Support for conditional hidding/showing/removal of elements based on values
Super lightweight with only 2.5kB of compressed Javascript
And more...

Quick Introduction

First you need to include one Javascript and CSS file provided you already use jQuery on your page.

Example: Replace … with the real path pointing to your files.

<!doctype html>
<html>
	<head>
		<script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>

		<link rel="stylesheet" type="text/css" href="…/template.css"/>
		<script src="…/jquery.template.min.js"></script>
	</head>
	<body>

	</body>
</html>

Now you can add the z-var="PROPERTY TARGET" attribute to any element and then call $(element).template(...) on that element or any parent.

The z-var attribute holds (comma-separated) instruction(s) specifying what should be replaced and where or what should be done.

The TARGET is usually . (dot) to insert the value as text in the element or @ATTR_NAME to insert variable into attribute. It is simple and you will understand it in a minute by looking at examples bellow or by jumping to the syntax section.

Let's see how it works in real world.

Assume that all examples in this section use this Javascript to apply the template. We pass quite complex data object to the template. The values in the object will be inserted in various points defined by z-var in HTML as you will see bellow.

$('.target').template({
	'name': 'John Smith',
	'validated': true,
	'list': ['aa', 'bb'],
	'listExt': [
		{'first': 'John', 'last': 'Doe', 'validated': true},
		{'first': 'Jane', 'last': 'Smith', 'validated': false}
	]
});

Now the examples that we apply the code to.

Example:

<div class="target" z-var="name ., validated .lock-icon"></div>
<input class="target" type="checkbox" z-var="validated @checked"/><label>Checked</label>

Result:

<div class="target lock-icon" z-var="name ., validated .lock-icon">John Smith</div>
<input class="target" type="checkbox" z-var="validated @checked" checked="checked"/><label>Checked</label>

Explanation:

"name ." - add value name as the text value
"validated .lock-icon" - add class lock-icon if validated is true
"validated @checked" - add checked="checked" attribute if true

Try it now!

Example:

<div class="target" z-var="validated ?">Validated</div>
<div class="target" z-var="!validated ?">Not Validated</div>
<div class="target" z-var="!validated !">Insecure</div>

Result:

<div class="target" z-var="validated ?">Validated</div>
<div class="target" z-var="!validated ?" style="display: none;">Not Validated</div>

Explanation:

"validated ?" - show element if validated is true, hide otherwise
"!validated ?" - the oposite of above - hide if true, show if false
"!validated !" - remove (destructive) the element if validated is false

Try it now!

Example:

<div class="target" z-var="name .">My name is ${name}</div>

Result:

<div class="target" z-var="name .">My name is John Smith</div>

Explanation:

"name ." - add value of name in place of ${name} placeholder

Try it now!

Example:

<ul class="target">
  <li template="[list]" z-var="value ."></li>
</ul>

Result:

<ul class="target">
  <li z-var="value ." class="template-clone" template-clone="[list]">aa</li>
  <li z-var="value ." class="template-clone" template-clone="[list]">bb</li>
  <li template="[list]" z-var="value ."></li><!-- invisible -->
</ul>

Explanation:

Duplicate the element with template="[list]" attribute for each value inside list array and

value . insert the array value as plain text into the element
All elements with an attribute template are automatically hidden by template.css you've included on the page (see above)

Try it now!

Example:

<ul class="target">
  <li template="[listExt]" z-var="first ., last ., last @title">${first} ${last}</li>
</ul>

Result:

<ul class="target">
  <li z-var="first ., last ., last @title" class="template-clone" template-clone="[listExt]" title="Doe">John Doe</li>
  <li z-var="first ., last ., last @title" class="template-clone" template-clone="[listExt]" title="Smith">Jane Smith</li>
  <li template="[listExt]" z-var="first ., last ., last @title">${first} ${last}</li><!-- invisible -->
</ul>

Explanation:

Duplicate the element with template="[listExt]" attribute for each value inside listExt array and use respective value object to insert variables into duplicated element as follows

"first ., last ." - add first and last name as text in positions indicated by ${PROP_NAME} placeolders
"last @title" - add last name into title attribute

Try it now!

Interactive Examples

The best example is the one you can play with.

Basic example - insert variable into attribute and text
Simple list example - iterate through the array and generate list
Simple Paging - simple list with paging
Mixed list example - simple variables with nested array to generate list
Form example - toggle check-boxes, set values on select-boxes, change button labels and classes...
UI Updates - example of continuous live UI updates

Syntax

Javacript

 $(SELECTOR).template(DATASET [, IN_PLACE]);

DATASET - Object or Array of Objects or Object with nested Arrays or Objects with properties and their values to be used when resolving z-var attributes.
IN_PLACE - boolean value. true: don't clone the element prior to replacing variables, false: clone the element, undefined: clone if element has the attribute template otherwise replace vars in-place without cloning.

HTML

	<element z-var="[!]DATASET_PROPERTY (TARGET|ACTION)[, ...]">...</element>

DATASET_PROPERTY - property name on the object passed to $(selector).template(DATASET) method.
TARGET - use following notation
- . - to insert value as TextNode,
- @ATTR_NAME to insert value into attribute (Note: If DATASET_PROPERTY si true then attribute's value will be same as attribute's name, e.g. checked="checked" for z-var="isChecked @checked" if isChecked = true.)
- + - load serialized HTML text in variable as child HTML,
- = - set variable's value as form field's value. If the field is a check-box or radio-box then (un)check it if value is boolean otherwise check it only if value equals to input's value attribute.
ACTION - following actions are available
- ? - hide element if value is false,
- ! - remove element if value is false (note: this is destructive action - you cannot re-apply new dataset again with the same effect),
- .CLASS_NAME - add/remove class if value is true/false.
! - "not" - negates the DATASET_PROPERTY value for the purpose of evaluation what ACTION should be taken.

To determine if ACTION should be taken DATASET_PROPERTY is converted into boolean true or false. Following values are considered false:

an empty Array
an empty Object
number 0
string representing numeric value zero (e.g. "0.00")
boolean false
null
empty string

If you try to insert the plain Array object as text or value then its length gets inserted instead. You can use it to insert item counts.

	<element template="(NAME|[PROPERTY])">...</element>

NAME - any name of your choice. All elements having attribute template are hidden by default (make sure to include the template.css). Applying template to such element will clone it, remove the template attribute and then apply the dataset. See Simple list example.
PROPERTY - name of the property on DATASET object that holds nested Array or Object to be automatically applied to this template. See Mixed list example.

For more advanced examples and explanations see file tutorial/index.html or just drop me a message what part is unclear and I will update this documentation...

hugovalepereira/jquery-dna-template

Features

Quick Introduction

Interactive Examples

Syntax

Javacript

HTML

More