dna-engine

An uncomplicated user interface library for cloning semantic templates

Fork me on GitHub

Documentation

For an overview of using dna-engine, see the Bookstore Example.

For richer examples, view the HTML source of the project visual specification runner.

dna-engine v is powering the interactive examples on this page.

Terminology and Browser Support

Terminology

Template:
An HTML element whose clones are injected with data from JavaScript objects.  The element has the dna-template class.
Data Field:
Data fields identify where in the template data is to be injected during the cloning process.  The name of the data field (object property) is surrounded by a pair of double tildes (example: ~~author~~).  Mustache notation with curly braces ({{ and }}) is also supported.
Clone:
A DOM element that is made by copying a template. The template name is added as each clone's class name.

Browser Support

Web Browsers:
dna-engine supports Chrome, Firefox, IE/Edge, Opera, and Safari.  It also runs on Node.js with jsdom.
Versions:
dna-engine requires jQuery 3.4 or above, and it has the same system requirements and browser support as the version of jQuery you use.

Setup JS and CSS Assets

  1. CDN
  2. Install with npm
  3. Install with webpack

Get started by including the JavaScript and CSS files into your project.

CDN

The jsDelivr CDN makes it easy to get started.

Load CSS file

            <link rel=stylesheet href=https://cdn.jsdelivr.net/npm/dna-engine@2.3/dist/dna-engine.css>
         
Load JavaScript libraries

            <script src=https://cdn.jsdelivr.net/npm/jquery@3.6/dist/jquery.min.js></script>
            <script src=https://cdn.jsdelivr.net/npm/dna-engine@2.3/dist/dna-engine.min.js></script>
         

Alternatively, you can use one of the methods below to download the dna-engine files into a folder in your project.

Install with npm

npm can download the assets to your project's node_modules folder.

npm

            $ npm install jquery dna-engine
         

package.json

            ...
            "dependencies": {
               "dna-engine": "~2.3",
               "jquery": "~3.6"
            }
            ...
         
Import into project

            import { dna } from 'dna-engine';
         

You can also run dna-engine headless (no browser) on Node.js with the DOM provided by jsdom.  See the sample project: node-jsdom-starter

Install with webpack

webpack treats the dna-engine library as a module.  Use import statements in your application to pull in the library's CSS and JavaScript.

Then use dna.registerContext() to expose your application so its functions can be used as callbacks from web pages.

webpack

            // Imports
            import 'dna-engine/dist/dna-engine.css';
            import $ from 'jquery';
            import 'dna-engine';

            // Application
            const myApp = {
               doSomething() { ... },
               };

            // Initialization
            const dna = globalThis.dna.initGlobal(window, $);
            dna.registerContext('myApp', myApp);
         

Check out the sample webpack project: webpack-to-do-app.

HTML — Classes, Fields, Attributes, and Properties

Template

Use the class dna-template to indicate a template.  The id attribute of the element is the template name.

Example HTML

            <p id=book class=dna-template>
         

Best practice is to wrap each template in a container element.

Example HTML for a wrapped template

            <h1>List of Books</h1>
            <section class=books>
               <div id=book class=dna-template>
                  <h2>~~title~~</h2>
               </div>
            </section>
         

Wrapping templates improves performance and is more semantic because multiple clones (plural) are closely related and belong in a group (singular).

Data Field

Enclose data field names in double tildes.  Each field takes up the entire text part of the HTML node.

Example HTML

            <span>~~title~~</span>
         

The field name refers to the property of the data object.  If the data is a simple literal (string, number, or boolean) rather than an object, use the special name [value] for the field.

Example HTML

            <span>~~[value]~~</span>
         

Element Attribute

Attributes are set using the same notation as fields.

Example HTML

            <div id=~~code~~>
         

Note: See Element Attribute (advanced) for alternate ways to set the value of an attribute.

Element Property

Properties are enabled or disabled based on the value of the specified data field.

Example HTML

            <input type=checkbox data-prop-checked=~~isGift~~> Gift Wrap<br>
            <input type=checkbox data-prop-checked=~~isExpress~~> Overnight
         

Valid data attributes for setting a property are data-prop-checked, data-prop-selected, and data-prop-deleted.

Select Option

The current selected option of a select drop-down is set based on the value of the specified data field matching the value attribute of the option element.

Example HTML

            <select data-option=~~category~~>
               <option disabled selected>Select category</option>
               <option value=art>Arts and humanities</option>
               <option value=sci>Science</option>
               <option value=med>Medical</option>
            </select>
         

The data-change attribute can be used in combination with the data-option attribute to fire a callback that gets the current data model whenever the user selects a new drop-down option.

To make the drop-down list data-driven, the options can be defined by an array in the data object.

Example JavaScript

            {
               category: 'sci',
               categories: [
                  { code: 'art', label: 'Arts and humanities' },
                  { code: 'sci', label: 'Science' },
                  { code: 'med', label: 'Medical' }
               ]
            }
         

Example HTML with data-driven options

            <select data-option=~~category~~>
               <option disabled selected>Select category</option>
               <option data-array=~~categories~~ value=~~code~~>~~label~~</option>
            </select>
         

Class

A class can be set just like other attributes.

Example HTML

            <div class=~~type~~>
         

However, the regular attribute technique above wipes out existing classes on the element, so it is generally better to the use the data-class attribute to add a class.

Example HTML (simple data field name)

            <div data-class=~~type~~>
         

If there are two or three names (comma separated), the first name is still the name of the data field but the data field is evaluated for "real" truth.

Example HTML (three names)

            <div data-class=~~onSale,highlight,no-highlight~~>
         

For true, the second name is added to the element as a class name while the class for third name, if provided, is removed.  For false, the third name, if provided, is added to the element as a class name while the class for second name is removed.

NameUseDescription
1stData field nameData for class name or truthiness
2ndClass name (for true)Class added to element for true
3rdClass name (for false)Class added to element for false

Continuing with the example of the onSale data field, the code below would result in the first book containing an element with the class highlight and the second book containing an element with the class no-highlight.

Example HTML

            <div id=book class=dna-template>
               <h2 data-class=~~onSale,highlight,no-highlight~~>~~title~~</h2>
            </div>
         

Example JavaScript

            const books = [
               { title: 'The DOM',     onSale: true },
               { title: 'Styling CSS', onSale: false }
               ];
            dna.clone('book', books);
         

Resulting HTML

            <div class=book>
               <h2 class=highlight>The DOM</h2>
            </div>
            <div class=book>
               <h2 class=no-highlight>Styling CSS</h2>
            </div>
         

Ensemble

Below is an example of a completed template.

Example HTML

            <div id=book class=dna-template>
               <h2 id=~~code~~>~~title~~</h2>
               <div data-class=~~type~~>
                  Author: <cite>~~author~~</cite>
               </div>
            </div>
         

Element Attribute (advanced)

In addition to using regular templating to set attributes, you can prefix data-attr- to the attribute name.

Example HTML for src attribute

            <img src=# data-attr-src=~~url~~ alt=avatar>
         

The prefixing technique enables setting the src attribute for an img element without causing the browser to fetch the image until the src attribute is actually set (adding src=# ensures the HTML is still valid according to the W3 HTML Validator).  This technique can also be used to set the id when the regular technique would result in duplicate IDs.

Similarly, data-attr-type can be used a as a warning free way set HTML5 values for the type attribute on input tags.

Example HTML for date and color fields

            Due date:    <input data-attr-type=date  value=~~dueDate~~><br>
            Cover color: <input data-attr-type=color value=~~coverColor~~>
         

Resulting HTML

            Due date:    <input type=date  value=2017-12-31><br>
            Cover color: <input type=color value=#daa520>
         

Setting HTML5 type values with the data-attr-type attribute avoids browser warnings such as:

Formatters

Formatters Overview
  1. Currency Format
  2. Date Format
  3. Number Format
  4. Percent Format
  5. Custom Format Function

A formatter converts a field of the data model so it is rendered in the desired format.

Note: Formatters work on individual model fields while transformers work on the whole data model object.  A transformer can operate on multiple fields, but it's generally simpler and cleaner to use a formatter.

Currency Format

Set the value of the data-format-currency attribute to an ISO 4217 currency code, such as jpy or usd, to format a currency field to display monetary values like "¥3,000" and "$4.95".

For data stored as a minor unit currency, use data-format-currency100 instead.  Best practice is to store to monetary values as integers rather than floats.  For example, a price of $29.99 should generally be stored as the integer value 2999 not as a float.

Example HTML for rendering jpy and eur currencies

            <div id=book class=dna-template>
               <p>Japan:  <span data-format-currency=jpy>~~price~~</span></p>
               <p>Greece: <span data-format-currency100=eur>~~price~~</span></p>
            </div>
         

Resulting HTML

            <div class=book>
               <p>Japan:  <span>¥2,999</span></p>
               <p>Greece: <span>€29.99</span></p>
            </div>
         

List of ISO 4217 currency codes:
https://en.wikipedia.org/wiki/ISO_4217#Active_codes

Example Currency Formatting
Code Minor Unit Template HTML Example Value Example Display
gbp data-format-currency=gbp 1234.5678 £1,234.57
krw data-format-currency=krw 1234.5678 ₩1,235
eur data-format-currency=eur 2999 €2,999.00
eur data-format-currency100=eur 2999 €29.99
usd data-format-currency=usd 2999 $2,999.00
usd data-format-currency100=usd 2999 $29.99

Date Format

Use the data-format-date attribute to format the rendering of a date field.

The date field is a number representing the milliseconds elapsed since the UNIX epoch (example: 1904112000000) or an ISO 8602 timestamp string (example: '2030-05-04T08:00:00.000Z').

Example HTML for rendering general and utc dates

            <div id=event class=dna-template>
               <p>Date: <span data-format-date=general>~~timestamp~~</span></p>
               <p>UTC: <span data-format-date=utc>~~timestamp~~</span></p>
            </div>
         

Resulting HTML

            <div class=event>
               <p>Date: <span>2030-05-04 1:00am Sat</span></p>
               <p>UTC: <span>Sat, 04 May 2030 08:00:00 GMT</span></p>
            </div>
         

There are 14 format codes for the data-format-date attribute.

Supported Date Formats
Format Code Example Output Display Time Zone
date Sat May 04 2030 local
general 2030-05-04 1:00am Sat local
general-date2030-05-04 local
general-day Sat local
general-time1:00am local
iso 2030-05-04T08:00:00.000Z UTC
locale 5/4/2030, 1:00:00 AM local
locale-date 5/4/2030 local
locale-time 1:00:00 AM local
string Sat May 04 2030 01:00:00 GMT-0700 (PDT)local
time 01:00:00 GMT-0700 (PDT) local
timestamp 2030-05-04@08:00:00 UTC
timestamp-ms2030-05-04@08:00:00.000 UTC
utc Sat, 04 May 2030 08:00:00 GMT UTC

Number Format

Use the data-format-number attribute to format numbers. Set the value to #, #.#, #.##, #.###, etc. to configure the fixed-point notation display.

Example HTML for rendering an integer and a float

            <div id=book class=dna-template>
               <p>Copies Sold: <span data-format-number=#>~~copiesSold~~</span></p>
               <p>Rating:      <span data-format-number=#.#>~~rating~~</span></p>
            </div>
         

Resulting HTML

            <div class=book>
               <p>Copies Sold: <span>1,327,842</span></p>
               <p>Rating:      <span>4.0</span></p>
            </div>
         
Example Number Formatting
Template HTML Example Value Example Display
data-format-number=#.#### -7 -7.0000
data-format-number=# 1234.5678 1,235
data-format-number=#.# 1234.5678 1,234.6
data-format-number=#.## 1234.5678 1,234.57
data-format-number=#.### 1234.5678 1,234.568

Percent Format

Use the data-format-percent attribute to format ratios (generally 0 to 1) as percentages, such as "93%" or "2.70%".  Set the value to #, #.#, #.##, #.###, etc. to configure the fixed-point notation display.

Example HTML for rendering an integer and a float

            <div id=book class=dna-template>
               <p>Score:         <span data-format-percent=#>~~score~~</span></p>
               <p>Foreign Sales: <span data-format-percent=#.#>~~sales.foreign~~</span></p>
            </div>
         

Resulting HTML

            <div class=book>
               <p>Score:         <span>90%</span></p>
               <p>Foreign Sales: <span>12.2%</span></p>
            </div>
         
Example Percent Formatting
Template HTML Example Value Example Display
data-format-percent=#.### -1 -100.000%
data-format-percent=# 0.12345678 12%
data-format-percent=#.# 0.12345678 12.3%
data-format-percent=#.## 0.12345678 12.35%

Custom Format Function

Use the data-format attribute to specify a custom formatting function that takes the value of the field and returns a string to render.

Example HTML with two custom formatters

            <div id=book class=dna-template>
               <p>Title:     <span data-format=app.formatTitle>~~title~~</span></p>
               <p>Character: <span data-format=String.fromCharCode>~~ascii~~</span></p>
            </div>
         

Example JavaScript

            const app = {
               formatTitle(title) {
                  return `"${title.toUpperCase()}"`;
                  },
               };
            const book = { title: 'Styling CSS', ascii: 8721 };  //sum symbol
            dna.clone('book', books);
         

Resulting HTML

            <div class=book>
               <p>Title:     <span>"STYLING CSS"</span></p>
               <p>Character: <span>∑</span></p>
            </div>
         

Note: The optional second parameter passed into the formatter function is the data model object.

JavaScript API (Essential)

API Overview
  1. dna.clone(name, data, options)
  2. dna.getClone(elem, options)
  3. dna.getModel(nameOrClone)
  4. dna.refresh(clone, options)
  5. dna.insert(name, data, options)

dna.clone(name, data [, options])

Generates a copy of the template and populates the fields, attributes, and classes from the supplied data.

Parameters:
  • Name of the template to clone.
  • Data to be used for populating the template fields when cloning the template.  If data is an array, the length of the array is the number of clones to be generated.
    • Smoothly transition clone elements (default: false).
    • Prepend new clone element (default: false).
    • Number of times to clone the data (default: 1).
    • Inject data as HTML rather than the default text (default: false).
    • Clear out existing clones first (default: false).
    • Container element to move clone into when using nested templates (default: null).
    • Task to mutate (enhance) data before it is used to create a clone.  The form is (data) => { ... }, where data is the data object applied to that clone (default: null).
    • Task to be run at the end of cloning.  The form is (elem, data) => { ... };, where elem is the jQuery object for the clone and data is the data object applied to that clone (default: null).
Example JavaScript

            dna.clone('book', { title: 'The DOM', author: 'Bo' });
         

dna.getClone(elem[, options])

Returns the clone (or sub-clone) for the specified element.

Parameters:
  • Any element within the clone or even the clone itself.
    • If true, ignore sub-clones and only search for the clone generated from the main template (default: false).
Example

            <div id=book class=dna-template>
               <p>~~title~~</p>
               <button data-click=setFavorite>I Like</button>
            </div>
            <script>
               const setFavorite = (buttonElem) => {
                  dna.getClone(buttonElem).addClass('favorite');
                  };
               dna.clone('book', { title: 'Go JavaScript!' });
            </script>
         

Resulting HTML (before clicking button)

            <div class=book>
               <p>Go JavaScript!</p>
               <button>I Like</button>
            </div>
         

Resulting HTML (after clicking button)

            <div class="book favorite">
               <p>Go JavaScript!</p>
               <button>I Like</button>
            </div>
         

dna.getModel(clone)

Returns the underlying data of the clone.

Parameters:
  • An element returned from a call to the dna.clone() method.
    • If true, ignore sub-clones and only search for the clone generated from the main template (default: false).
Example JavaScript

            const book = { title: 'The DOM', author: 'Bo' };
            const clone = dna.clone('book', book);
            const model = dna.getModel(clone);
            model.title = 'The DOM II';
            dna.refresh(clone);  //updates ui (DOM element) with new title
         

Note: To get the data for all the clones of a template, pass in the template name (String).  For example, dna.getModel('book') will return an array of book objects.

dna.refresh(clone[, options])

Updates an existing clone to reflect changes to the data model.

Parameters:
  • An element returned from a call to the dna.clone() method.
    • New values for the data model.  Only data model fields that are contained in the data option are updated. (default: null).
    • If true, ignore sub-clones and only search for the clone generated from the main template (default: false).
    • Inject data as HTML rather than the default text (default: false).
Example JavaScript

            const book = { title: 'The DOM', author: 'Bo' };
            const clone = dna.clone('book', book);
            const model = dna.getModel(clone);
            model.title = 'The DOM II';
            dna.refresh(clone);  //updates ui (DOM element) with new title
         

dna.insert(name, data [, options])

For the specified template, updates the first clone if it already exists otherwise creates the first clone.

In cases where only a single clone is needed to provide simple templating for fields that appear just once on a web page, call dna.insert().  Unlike dna.clone(), this function will only create a new clone if needed.

Parameters:
  • Name of the template to clone.
  • Data to be used for populating the template fields when cloning the template.  If data is an array, the length of the array is the number of clones to be generated.
    • Smoothly transition clone elements (default: false).
    • Inject data as HTML rather than the default text (default: false).
    • Task to mutate (enhance) data before it is used to create a clone.  The form is (data) => { ... }, where data is the data object applied to that clone (default: null).
    • Task to be run at the end of cloning.  The form is (elem, data) => { ... };, where elem is the jQuery object for the clone and data is the data object applied to that clone (default: null).
Example JavaScript

            dna.insert('book', { title: 'The DOM', author: 'Bo' });
         

JavaScript API (Extra/Advanced)

API Overview
  1. dna.arrayPush(holderClone, arrayField, data, options)
  2. dna.empty(name, options)
  3. dna.refreshAll(name)
  4. dna.recount(name, options)
  5. dna.destroy(clone, options)
  6. dna.getClones(name)
  7. dna.getIndex(elem, options)
  8. dna.up(elemOrEventOrIndex)
  9. dna.down(elemOrEventOrIndex)
  10. dna.bye(elemOrEventOrIndex)
  11. dna.registerInitializer(callback, options)
  12. dna.clearInitializers()
  13. dna.registerContext(contextName, contextObjectOrFunction)
  14. dna.info()

dna.arrayPush(holderClone, arrayField, data[, options])

Clones a sub-template to append onto an array loop.

Parameters:
  • Clone element that contains the sub-template array loop.
  • Name of data field for an array loop.
  • Data to be used for populating the template fields when cloning the template.  If data is an array, the length of the array is the number of clones to be generated.
    • Smoothly transition clone elements (default: false).
    • Prepend new clone element (default: false).
Example JavaScript

            const book = { title: 'Interwebz', chapters: ['ARPANET', 'TCP/IP'] };
            const clone = dna.clone('book', book);
            const options = { fade: true, top: false };
            dna.arrayPush(clone, 'chapters', 'CERN', options);  //append chapter
         

See the Sub-templates (array loops) section for details.

dna.createTemplate(name, html, holder)

Generates a template from an HTML string.

Parameters:
  • Name of the template to clone.
  • HTML string representation of a template.  The html represents a template with exactly one node at its root.  No id or class attributes are required.
  • Container element to hold clones that are created from the template.
Example JavaScript

            const books = [
               { title: 'The DOM' },
               { title: 'Go JavaScript!' },
               { title: 'Styling CSS3' }
               ];
            const html = '<li>~~title~~</li>';
            dna.createTemplate('book', html, $('ol#book-list'));
            dna.clone('book', books);
         

Resulting HTML

            <ol id=book-list>
               <li class=book>The Dom</li>
               <li class=book>Go JavaScript!</li>
               <li class=book>Styling CSS3</li>
            </ol>
         

dna.templateExists(name)

Reports if a template is present.

Parameters:
  • Name of the template to clone.
Example JavaScript

            if (dna.templateExists('book'))
               dna.clone('book', books);
         

dna.empty(name[, options])

Deletes all clones generated from the template.

Parameters:
  • Name of the template to clone.
    • Smoothly transition clone elements (default: false).
Example JavaScript

            dna.empty('book', { fade: true });
         

The dna.empty() method does not delete sub-clones generated from nested templates.

dna.refreshAll(name)

Updates all the clones of the specified template.

Parameters:
  • Name of the template to clone.
    • New values for the data model.  Only data model fields that are contained in the data option are updated. (default: null).
    • If true, ignore sub-clones and only search for the clone generated from the main template (default: false).
    • Inject data as HTML rather than the default text (default: false).
Example JavaScript

            const clone1 = dna.clone('book', { title: 'The DOM' });
            const clone2 = dna.clone('book', { title: 'Styling CSS' });
            dna.getModel(clone1).title = 'The DOM II';    //modified title
            dna.getModel(clone2).title = 'Styling CSS3';  //modified title
            dna.refreshAll('book');  //updates ui with new titles
         

dna.recount(clone[, options])

Renumbers the counters starting from 1 for the clone and its siblings based on DOM order.

When using the special field [count], you may need to renumber the counters after moving, inserting or deleting clones.

Parameters:
  • An element returned from a call to the dna.clone() method.
    • Inject data as HTML rather than the default text (default: false).
Example JavaScript

            const books = [
               { title: 'The DOM' },         //count: 1
               { title: 'Go JavaScript!' },  //count: 2
               { title: 'Styling CSS3' }     //count: 3
               ];
            const clones = dna.clone('book', books);
            dna.down(clones.first());   //move "The DOM" to be just after "Go JavaScript!"
            dna.recount(clones.eq(1));  //set "Go JavaScript!" count to 1 and "The DOM" to 2
         

dna.destroy(clone[, options])

Removes an existing clone from the DOM.

Parameters:
  • An element returned from a call to the dna.clone() method.
    • Smoothly transition clone elements (default: false).
    • If true, ignore sub-clones and only search for the clone generated from the main template (default: false).
    • Task to be run at the end of cloning.  The form is (elem, data) => { ... };, where elem is the jQuery object for the clone and data is the data object applied to that clone (default: null).
Example JavaScript

            const clone = dna.clone('book', book);
            dna.destroy(clone, { fade: true });
         

Note: If the only option being set is fade to true, it is simpler to user the dna.bye() convenience method.

dna.getClones(name)

Returns an array of all the existing clones for the given template.

Parameters:
  • Name of the template to clone.
Example JavaScript

            const books = dna.getClones('book');
         

dna.getIndex(elem[, options])

Returns the index of the clone.

Parameters:
  • Any element within the clone or even the clone itself.
    • If true, ignore sub-clones and only search for the clone generated from the main template (default: false).

dna.up(elemOrEventOrIndex)

Smoothly moves a clone up one slot effectively swapping its position with the previous clone.

Parameters:
  • Reference to a jQuery element.
Example: Event callbacks for up and down

            <div id=book class=dna-template>
               <p>~~title~~</p>
               <button data-click=dna.up>Move Up</button>
               <button data-click=dna.down>Move Down</button>
            </div>
         

Users are able to interactively rearrange the clones by clicking the Move Up and Move Down buttons.

dna.down(elemOrEventOrIndex)

Smoothly moves a clone down one slot effectively swapping its position with the next clone.

Parameters:
  • Reference to a jQuery element.

See the example for dna.up().

dna.bye(elemOrEventOrIndex)

Performs a sliding fade out effect on the clone and then removes the element.  The function can be called: 1) as an event callback, 2) from a jQuery loop, or 3) directly with the clone as the parameter.

Parameters:
  • Reference to a jQuery element.
Example 1: Event callback

            <div id=book class=dna-template>
               <p>~~title~~</p>
               <button data-click=dna.bye>Delete Book</button>
            </div>
         
Example 2: jQuery loop

            $('.book.favorite').each(dna.bye);  //deletes all favorite books
         
Example 3: Direct function call

            const clone = dna.clone('book', { title: 'The DOM' });
            dna.bye(clone);  //deletes 'The DOM'
         

Note 1: The element identifying the clone can be a sub-element within the clone or the clone itself.

Note 2: The clone to be removed can be either a main clone or a sub-clone.

dna.registerInitializer(callback[, options])

Adds a callback function to the list of initializers that are run on all DOM elements.

Parameters:
  • String name of a function or an actual function.
    • CSS selector (default: none).
    • A single value to pass into the function or an array of values where each element in the array is a parameter passed into the function.
    • Run the initializer on the web page ($(globalThis.document)) once the page loads (default: true).
Example JavaScript

            // Line below replaces:  $('.comment-form').validate();
            dna.registerInitializer('validate', { selector: '.comment-form' });
         

See the Initializers section for details.

dna.clearInitializers()

Deletes all initializers.

Example JavaScript

            dna.registerInitializer('bootstrapSwitch', '.switch');
            dna.clearInitializers();  //undoes previous line
         

See the Initializers section for details.

dna.registerContext(contextName, contextObjectOrFunction)

Registers an application object or individual function to enable it to be used for event callbacks.  Registration is needed when global namespace is not available to dna-engine, such as when using webpack to load dna-engine as a module.

Parameters:
  • Name of the object or function to register.
  • The object or function being registered.

See the webpack section for more information.

dna.info()

Returns status information about templates on the current web page.

Example JavaScript

            dna.info();
         

The dna.info() method is intended to be called manually from the console to see which templates have been detected and compiled.

Looping

Template Array Loops

Pass in a single object to create one clone.  Pass in an array of objects to create multiple clones.

Example HTML

            <div id=book class=dna-template>~~title~~</div>
         

Example JavaScript

            const books = [
               { title: 'The DOM' },
               { title: 'Interwebz' }
               ];
            dna.clone('book', books);
         

Resulting HTML

            <div class=book>The DOM</div>
            <div class=book>Interwebz</div>
         

Sub-templates (array loops)

Use the data-array attribute to create a sub-template for data fields that are arrays.  Each element of the array will clone the sub-template to generate a sub-clone within the main clone.

Example HTML

            <div id=book class=dna-template>
               Book: <span>~~title~~</span> by
               <span>
                  <span data-array=~~authors~~>~~[value]~~</span>
               </span>
               <div>
                  <div data-array=~~chapters~~>
                     Chapter: <span>~~header~~</span>
                  </div>
               </div>
            </div>
         

Example JavaScript

            const book = {
               title:    'Interwebz',
               authors:  ['Ed', 'Jake', 'Abby'],
               chapters: { header: 'ARPANET', header: 'TCP/IP' }
               };
            dna.clone('book', book);
         

Resulting HTML

            <div class=book>
               Book: <span>Interwebz</span> by
               <span>
                  <span>Ed</span>
                  <span>Jake</span>
                  <span>Abby</span>
               </span>
               <div>
                  <div>
                     Chapter: <span>ARPANET</span>
                  </div>
                  <div>
                     Chapter: <span>TCP/IP</span>
                  </div>
               </div>
            </div>
         

Arrays of Primitives (strings, numbers, booleans)

The special field [value] tells the template to use simple values from an array of primitives.  The special field [count] is the value's index number in the array plus 1.

Example HTML

            <div id=book class=dna-template data-title=~~[value]~~>
               <span>~~[count]~~</span>. <span>~~[value]~~</span>
            </div>
         

Example JavaScript

            const books = ['The DOM', 'Interwebz'];
            dna.clone('book', books);
         

Resulting HTML

            <div class=book data-title="The DOM">
               <span>1</span>. <span>The DOM</span>
            </div>
            <div class=book data-title="Interwebz">
               <span>2</span>. <span>Interwebz</span>
            </div>
         

Note: After moving, inserting, or removing clone elements, you can reset the counter for the special field [count] by calling dna.recount().

Separators

Use the data-separator and data-last-separator attributes to insert text between clones.  For example, this feature can put commas and the word "and" between authors in a list.  The two types of separators can be used together or individually.

Example

            <b>Authors:</b>
            <span id=author class=dna-template data-separator=", ">
               <span>~~name~~</span>
            </span>
            <script>
               const authors = [{ name: 'Ed' }, { name: 'Bo'}, { name: 'Jan' }];
               dna.clone('author', authors);
            </script>
         

Result
Authors: Ed, Bo, Jan

Note: For more advanced control, use the classes dna-separator and dna-last-separator on elements within the template.

Example using explicit separator nodes

            <b>Authors:</b>
            <span id=author class=dna-template>
               <span>~~name~~</span><span class=dna-separator>,</span>
               <span class=dna-last-separator>and</span>
            </span>
         

Result
Authors: Ed, Bo and Jan

Events, Callbacks, and Forms

Data Model Transformer

Essential to building semantic templates and keeping JavaScript out of your HTML is having a clean way to mutate (enhance) the data model.  Use the data-transform attribute to declare transformers that implement your business logic.

The transformer function receives the clone's data model so it can modify the model before the clone element is created.

Example HTML

            <div id=book class=dna-template data-transform=enhanceBook>
               <span>~~title~~</span>
               <img src=star.png alt=star data-true=~~displayStar~~>
            </div>
         

Example JavaScript

            const enhanceBook = (data) => {
               data.displayStar = data.rating > 3;  //good books get a star
               };
            const books = [
               { title: 'The DOM',   rating: 2 },
               { title: 'Interwebz', rating: 5 }
               ];
            dna.clone('book', books);
         

Resulting HTML

            <div class=book>
               <span>The DOM</span>
            </div>
            <div class=book>
               <span>Interwebz</span>
               <img src=star.png alt=star>
            </div>
         

Note 1: The transform function can also be passed as an option when cloning, such as: dna.clone('book', books, { transform: enhanceBook })

Note 2: Transformers work on data model objects while formatters work on individual model fields.  A transformer can operate on multiple fields, but it's generally simpler and cleaner to use a formatter.

Element Callback

Use the data-callback attribute to declare a callback function for a template.  Cloning the template triggers the callback for each new clone, and the clone element and its data model are passed into the function.

In the example below, the span node of each new book clone is passed into the blink() function, causing the title to fade in a couple times as if it's blinking at the user.

Example HTML

            <div id=book class=dna-template>
               <span data-callback=blink>~~title~~<span>
            </div>
         
Example JavaScript

            const blink = (elem) => elem.fadeOut().fadeIn().fadeOut().fadeIn();
         

Note 1: A callback function can also be passed as an option, such as: dna.clone('book', books, { callback: blink });

Note 2: Element callbacks perform a similar function as initializers, but an element callback is specific and an initializer is general.  For example, an element callback is appropriate for an animation or initiating a REST call to retrieve additional data for the element while an initializer is appropriate for configuring tooltips that occur in any element.

Click, Change, and Key Events

Event bindings in dna-engine are done with data attributes directly on DOM elements that need to trigger callbacks.  The value assigned to the attribute is the name of the function to be called when the event occurs.  The jQuery element which triggered the event is passed into the callback function as the first parameter, and the event object is passed in as the second parameter.

Element attributes for supported events:
  1. data-click
  2. data-hover-in
  3. data-hover-out
  4. data-change
  5. data-input
  6. data-key-down
  7. data-key-press
  8. data-key-up
  9. data-enter-key
  10. data-focus-in
  11. data-focus-out
Example

            <output id=message></output>
            <p>Click:     <button data-click=showMsg     value=1>1</button></p>
            <p>Hover in:  <meter  data-hover-in=showMsg  value=2 max=4></meter> 2</p>
            <p>Hover out: <meter  data-hover-out=showMsg value=3 max=4></meter> 3</p>
            <p>Change:    <input  data-change=showMsg    value=4></p>
            <p>Input:     <input  data-input=showMsg     value=5></p>
            <p>Key down:  <input  data-key-down=showMsg  value=6></p>
            <p>Key press: <input  data-key-press=showMsg value=7></p>
            <p>Key up:    <input  data-key-up=showMsg    value=8></p>
            <p>Submit:    <input  data-enter-key=showMsg value=9></p>
            <p>Focus in:  <input  data-focus=showMsg     value=A></p>
            <p>Focus out: <input  data-focus=showMsg     value=B></p>
            <script>
               const showMsg = (elem, event) => {
                  const msg = 'Value "' + elem.val() + '" on ' + event.type;
                  $('#message').text(msg).stop().hide().fadeIn();
                  };
            </script>
         

Result (interactive)
 

Click:

Hover in: 2

Hover out: 3

Change:

Input:

Key down:

Key press:

Key up:

Submit:

Focus in:

Focus out:

Note: For text fields input and textarea, use data-smart-update.

Experiment with click events:

See how events can be used with FileReader() to make a reusable photo upload component:

Smart Update

Smart update callbacks are run only when a user changes the actual value of a text input, and the calls are throttled to be at least one second apart.

The data-smart-update attribute sets the callback, and the data-smart-throttle attribute sets the throttle rate in milliseconds to override the 1000 millisecond default.

Example

            <input data-smart-update=logNow placeholder="Type here">
            <div id=log-message class=dna-template>
               <code>~~message~~</code>
            </div>
            <script>
               const logNow = (elem) => {
                  const msg = Date.now() + ': ' + elem.val();
                  dna.clone('log-message', { message: msg }, { fade: true });
                  };
            </script>
         

Result (interactive)
~~message~~

Experiment with smart update events:

Smart update events can be used over WebSockets:
github.com/dna-engine/smart-update-websockets

screenshot
Example WebSockets server and client showing throttled live updates using dna-engine

Jump to page (URL)

Similar to the <a> anchor tag, the data-href attribute redirects the browser to the specified URL when the user clicks the element.

Example

            <button data-href=../book-finder.html>Book Finder</button>
         

Result (interactive)

Add class=external-site to tell the browser to open the link in a new tab (or window).

Add data-target=[WINDOW-NAME] to tell the browser to open the link in a named tab (or window).

Data Model Updating on Field Updates

The clone's data model is updated when a user edits or changes an input field.

Input FieldExample
text <input value=~~title~~>
checkbox <input type=checkbox data-prop-checked=~~set~~>
radio button <input type=radio name=cover data-prop-checked=~~set~~>
drop-down <select data-option=~~category~~>

The example below uses event bindings to call a function that reads the data model with dna.getModel().

Example HTML

            <h2>Book Information</h2>
            <div id=book class=dna-template>
               Title: <input value=~~title~~ data-key-up=bookInfo.update>
               ebook: <input type=checkbox data-prop-checked=~~ebook~~
                  data-change=bookInfo.update>
            </div>
            <div>Data: <code id=data>[YOUR MOVE]</code></div>
         

Example JavaScript

            const bookInfo = {
               update: (elem) => {
                  const data = JSON.stringify(dna.getModel(elem));
                  $('#data').text(data).hide().fadeIn();
                  },
               setup: () => {
                  const book = { title: 'Styling CSS', ebook: true };
                  dna.clone('book', book);
                  }
               };
            $(bookInfo.setup);
         

Update data model (interactive)

Book Information

Title:
ebook:

Data: [YOUR MOVE]

Note: While the original data used to clone the template may contain truthy values, the boolean values updated in the data model are set to actual true or false.

Initializers

On a static page where all the HTML is sent in a single HTTP response, any needed element initialization can be done one time just after page load.  For example, the line $('.tooltip').qtip(); could be used to setup all tooltips.  Cloning with dna-engine creates elements and adds them to the DOM after the page is loaded, and those new elements also need to be initialized.

When you register your initializer functions, dna-engine ensures DOM elements are setup even if the elements are added to the DOM via cloning after the page is loaded.

SelectorExampleInitializer
Yes { selector: '.tooltip' } Immediately run on selected elements (example: $('.tooltip')) and then on new clones
No n/a Only run on new clones

If the registered initializer function is a method on the jQuery element, dna-engine will execute the method on the element and use the params option for the parameters.  Otherwise, the element is passed into the function as the first parameter with the params supplied as additional parameters.

Example JavaScript

            const app = {

               setup() {
                  const highlight = (elem) => elem.css({ backgroundColor: 'gold' });

                  // Highlight each new clone
                  dna.registerInitializer(highlight);

                  // Setup tooltips for each new clone:  $('.tooltip').qtip();
                  dna.registerInitializer('qtip', { selector: '.tooltip' });

                  // Style each new clone:  $('.gap').css({ padding: '8px' });
                  const options = { selector: '.gap', params: { padding: '8px' } }
                  dna.registerInitializer('css', options);
                  },

               };

            $(app.setup);
         

Note 1: Initializers perform a similar function as element callbacks (data-callback), but an initializer is general to all clones and an element callback is specific to clones of one template.  For example, an initializer is appropriate for configuring tooltips that can occur in any clone.

Note 2: In the event that your application dynamically adds elements to the DOM without using dna-engine, it may be necessary to explicitly run the initializers by passing the root element of new elements into: dna.events.runInitializers(root);

Transform Option

The transform option for dna.clone() specifies a transformer function to mutate (enhance) the data model.

The transformer function receives the clone's data model so it can modify the model before the clone element is created.

Example HTML

            <div id=book class=dna-template>
               <span>~~title~~</span>
               <img src=star.png alt=star data-true=~~displayStar~~>
            </div>
         

Example JavaScript

            const enhanceBook = (data) => {
               data.displayStar = data.rating > 3;  //good books get a star
               };
            const books = [
               { title: 'The DOM',   rating: 2 },
               { title: 'Interwebz', rating: 5 }
               ];
            dna.clone('book', books, { transform: enhanceBook });
         

Resulting HTML

            <div class=book>
               <span>The DOM</span>
            </div>
            <div class=book>
               <span>Interwebz</span>
               <img src=star.png alt=star>
            </div>
         

Note: A transformer function can also be specified with the data-transform attribute, such as: <div id=book class=dna-template data-transform=enhanceBook>

Callback Option

The callback option for dna.clone() specifies a callback function.

Once cloning is completed, the callback function is executed and passed the clone element plus the data that was injected into the clone.

Example HTML

            <div id=book class=dna-template>
               ~~title~~
            </div>
         

Example JavaScript

            const applyBkgnd = (elem, data) => {
               elem.css({ backgroundImage: data.cover });
               };
            const options = { fade: true, callback: applyBkgnd };
            const book = { title: 'Taskmaster', cover: 'url(cover.png)' };
            dna.clone('book', book, options);
         

Resulting HTML

            <div class=book style="background-image: url(cover.png);">
               Taskmaster
            </div>
         

See the line dna.clone('circle', circles, { callback: addStyle }); used to create the dna-engine logo.

Note: A callback function can also be specified with the data-callback attribute, such as: <div id=book class=dna-template data-callback=blink>

On Load Functions

Use the data-on-load attribute to initiate a callback function after the document is ready.  The element with the data-on-load attribute is passed into on load function once the HTML is loaded.

The callback function is executed after the function plus any optional dependencies have been loaded.  Specify dependencies as a comma separated list using the data-wait-for attribute.

Example HTML

            <p data-on-load=blink data-wait-for=myEventLogger>
               This paragraph will blink on page load!
            </p>
            <script>
               const blink = (elem) => {
                  elem.fadeOut().fadeIn().fadeOut().fadeIn();
                  myEventLogger('Blink happened');
                  };
            </script>
         

Note #1: The data-on-load attribute can be used in conjunction with the dna.ui.focus function to auto-focus on an input element.

Note #2: The polling interval to check if the callback function and dependencies are loaded is 300 millisecond.  To display degbug information, including waiting time: console.log($('[data-on-load]').data());

Structures and Conditional Logic

Object Dot Notation (nested objects)

Use JavaScript object dot notation in field names to reference data fields of nested objects.

Example HTML

            <div id=book class=dna-template>
               First Name: <span>~~author.first~~</span>
            </div>
         

Example JavaScript

            const book = {
               title: 'The DOM',
               author: { first: 'Bo', last: 'Smith' }
               };
            dna.clone('book', book);
         

Resulting HTML

            <div class=book>
               First Name: <span>Bo</span>
            </div>
         

Template Placeholder

A template placeholder is only shown when its corresponding template is empty (has zero clones).  The data-placeholder attribute specifies the name of the template.

Example HTML

            <div class=books>
               <p id=book class=dna-template>~~title~~</p>
            </div>
            <div data-placeholder=book>No books</div>
         

The "No books" message is displayed until at least one book is cloned, and the message will be re-displayed if all the book clones are removed.

Thimblerig (conditional hide and seek logic)

Instead of writing JavaScript to show and hide DOM elements, use an attribute to declare whether the element should be shown or hidden.  dna-engine supports four conditionals — two for the existence of a field and two for the "real" truth of a field.

AttributeValueLogic
data-requireData FieldShow element only if specified field exists*
data-missingData FieldShow element only if specified field does not exist*
data-trueData FieldShow element only if specified field means true**
data-falseData FieldShow element only if specified field means false**
Example HTML

            <div id=book class=dna-template>
               <span data-require=~~title~~>~~title~~</span>
               <span data-missing=~~title~~>[not found]</span>
            </div>
         

Example JavaScript

            const books = [
               { author: 'Bo', title: 'The DOM' },
               { author: 'Jan' }
               ];
            dna.clone('book', books);
         

Resulting HTML

            <div class=book>
               <span>The DOM</span>
            </div>
            <div class=book>
               <span>[not found]</span>
            </div>
         
*Field Exists

A field in a data object exists if the field's value is not undefined or null.

**Real Truth

dna-engine evaluates if a data field is true or false based on rules designed to match the boolean meaning of data as it would be stored in a database or how the data would be interpreted in a business sense.  For example, the string 'FALSE' is evaluated to the boolean false when determining its "real" truth.

ValueExamples
Truthy true, 1, '1', 't', 'T', 'TRue', 'Y', 'yes', 77, [5], {}, 'Colbert', Infinity
Falsey false, 0, '0', 'f', 'F', 'faLSE', 'N', 'no', '', [], null, undefined, NaN
Transient Fields

Compact and maintainable code can be written by basing conditionals on transient data fields.

Example HTML

            <p class=warning data-true=~~overdue~~>Invoice past due!</p>
         
Example JavaScript

            const invoice = { amount: 125.00, due: 'April 3, 2015' },
            invoice.overdue = new Date(invoice.due).getTime() < Date.now();
            dna.clone('invoice', invoice);
         

In the above example, the invoice data object has an amount field and a due field.  The past due warning is displayed if the boolean field overdue, which is calculated on the fly, is set to true.

Note: Similar to thimblerigs, separators are used to hide and show a delimiter between clones, such as a comma to separate names of authors.

Nested Templates

For additional flexibility, templates can be nested and then explicitly cloned with calls to dna.clone().  A nested template belongs to a holder template, and the specific holder clone must be passed into dna.clone() when cloning a nested template.

View source for spec runner #07.

In most cases, a simple sub-template array loop is the better solution.

Hide a Container Element

Add the class dna-hide to a container element that should not be visible until after a descendant template is cloned.

Example component hidden until after cloning

            <section data-component=bookshelf class=dna-hide>
               <h2>Bookshelf</h2>
               <div class=books>
                  <h3 id=book class=dna-template>~~title~~</h3>
               </div>
            </section>
         

The data-component=bookshelf element is hidden until the book template is cloned, thus preventing the user from seeing the <h2>Bookshelf</h2> heading before there are any books.

Also see: data-placeholder

Making Reusable Components

Defining a Component

A reusable component is named using the data-component attribute on the container element.

The component can be initialized with an on load function (data-on-load) to make a REST call that gets data for a template.  Events with callbacks, such as a click event (data-click), pass back the target element, event object, and the component element.

Bookshelf Component CSS

            [data-component=bookshelf] .my-books .my-book {
               max-width: 400px;
               background-color: plum;
               padding: 5px 15px;
               margin-bottom: 15px;
               }
         

Bookshelf Component HTML and JavaScript

            <div data-component=bookshelf data-on-load=bookshelf.setup>
               <h2>Bookshelf</h2>
               <section class=my-books>
                  <div id=my-book class=dna-template>
                     <h3>~~title~~</h3>
                     Author: <cite>~~author~~</cite>
                  </div>
               </section>
               <button data-click=bookshelf.show>Show component name</button>
               <script>
                  const bookshelf = {
                     booksUrl: 'https://dna-engine.org/api/books/',
                     show: (elem, event, component) =>
                        elem.text(component.data().component + '!'),
                     setup: (elem) => {
                        const handle = (data) => dna.clone('my-book', data);
                        fetchJson.get(bookshelf.booksUrl).then(handle);
                        }
                     };
               </script>
            </div>
         

Result (with three books loaded from REST call)

Bookshelf

~~title~~

Author: ~~author~~

Example Photo Upload Component

See how events can be used with FileReader() to make a reusable photo upload component:

Panels (UI Tabs)

Panels are content elements associated with menu items.  When the user clicks a menu item, the corresponding panel is displayed (faded in) and the panel element is passed to the callback. 

Panel basics

Add the dna-menu class to the container of clickable menu items.  Add the dna-panels class to the container of panel elements.

Basic format for panels

            <nav class=dna-menu>
               <span>Menu item #1</span>
               <span>Menu item #2</span>
               <span>Menu item #3</span>
            </nav>
            <div class=dna-panels>
               <section>Content of panel #1</section>
               <section>Content of panel #2</section>
               <section>Content of panel #3</section>
            </div>
         

Place the panels container (.dna-panels) in the DOM immediately after the menu container (.dna-menu).

If the menu container and panels container need to be separated in the DOM, link the menu to the panels by setting their respective data-nav attributes to the same name.

Linked menu and panels using data-nav

            <nav class=dna-menu data-nav=author-info>
               <span>Menu item #1</span>
               <span>Menu item #2</span>
               <span>Menu item #3</span>
            </nav>
            <meter value=7 min=0 max=10></meter>
            <div class=dna-panels data-nav=author-info>
               <section>Content of panel #1</section>
               <section>Content of panel #2</section>
               <section>Content of panel #3</section>
            </div>
         

For an example of tabbed panel navigation, check out DataDashboard:
https://data-dashboard.js.org

Example panels

The interactive example below displays information for the user selected author.

Example CSS Less

            [data-component=author] {
               .dna-menu {
                  list-style-type: none;
                  padding: 0px;
                  margin-top: 10px;
                  .dna-menu-item {
                     display: inline;
                     background-color: lightskyblue;
                     border: 2px solid silver;
                     border-radius: 5px;
                     padding: 5px 10px;
                     transition: all 400ms;
                     &.dna-selected, &:hover {
                        border-color: dimgray;
                        }
                     }
                  }
               }
         

Example HTML

            <div data-component=author>
               <h2>Author Information</h2>
               Select:
               <ul class=dna-menu data-nav=author-info>
                  <li>Jake</li>
                  <li>Abby</li>
                  <li>Ed</li>
               </ul>
               <div class=dna-panels data-nav=author-info>
                  <section>
                     <h5>Name: Jake</h5>
                     <p>Publisher: O'Reilly</p>
                     <p>Agent: William and Associates</p>
                  </section>
                  <section>
                     <h5>Name: Abby</h5>
                     <p>Publisher: Addison-Wesley</p>
                     <p>Agent: Pro Reps</p>
                  </section>
                  <section>
                     <h5>Name: Ed</h5>
                     <p>Publisher: ASM International</p>
                     <p>Agent: Feven</p>
                  </section>
               </div>
            </div>
         

Result (interactive)

Author Information

Select:
  • Jake
  • Abby
  • Ed
Name: Jake

Publisher: O'Reilly

Agent: William and Associates

Name: Abby

Publisher: Addison-Wesley

Agent: Pro Reps

Name: Ed

Publisher: ASM International

Agent: Feven

Experiment with button navigation panels:

Experiment with drop-down navigation panels:

Template-Driven Panels

The interactive example below uses templates to build the menu and the panels.

Example HTML

            <div data-component=book-catalog data-on-load=bookCatalog.setup>
               <h2>Book Catalog</h2>
               <nav class=dna-menu data-nav=book-catalog>
                  <button id=book-menu-item class=dna-template>
                     ~~[count]~~
                  </button>
               </nav>
               <div class=dna-panels data-nav=book-catalog>
                  <section id=book-panel class=dna-template
                        data-transform=bookCatalog.addCover>
                     <h4>~~title~~</h4>
                     <img src=# data-attr-src=~~cover~~ alt=cover>
                  </section>
               </div>
               <script>
                  const bookCatalog = {
                     data: [
                        { id: 'RLG21IfQDckC', title: 'Designing Apps' },
                        { id: '_xB0PyT9Y24C', title: 'CSS3 Guide' },
                        { id: 'PXa2bby0oQ0C', title: 'The Good Parts' },
                        { id: '4x6Gj_0UHMsC', title: 'Pro jQuery' }
                        ],
                     addCover: (data) => {
                        data.cover = 'https://books.google.com/books/content?id=' +
                           data.id + '&printsec=frontcover&img=1&zoom=1';
                        },
                     setup: () => {
                        dna.clone('book-menu-item', bookCatalog.data);
                        dna.clone('book-panel',     bookCatalog.data);
                        }
                     };
               </script>
            </div>
         

Result (interactive)

Book Catalog

~~title~~

cover

Panel Routes

Create routes in dna-engine by adding a data-hash attribute to each panel element.  The value specified by data-hash becomes the fragment identifier (hash) in the URL.

Optionally, add a data-callback attribute on the menu element to run a function whenever a panel is displayed.  The callback function receives the panel element and fragment identifier (hash) for the currently displayed panel.

Example HTML

               <h2>Publishers</h2>
               <nav class=dna-menu data-nav=publisher-info data-callback=updatePanel>
                  <button>Pearson</button>
                  <button>Shueisha</button>
                  <button>Wiley</button>
               </nav>
               <div class=dna-panels data-nav=publisher-info>
                  <section data-hash=pearson>
                     <h2>Pearson</h2>
                     <p>UK</p>
                  </section>
                  <section data-hash=shueisha>
                     <h2>Shueisha</h2>
                     <p>Japan</p>
                  </section>
                  <section data-hash=wiley>
                     <h2>Wiley</h2>
                     <p>US</p>
                  </section>
               </div>
         

Example JavaScript

            const updatePanel = (panel, hash) => {
               const url = location.origin + location.pathname + '#' + hash;
               if (!panel.find('a').length)
                  panel.append($('<a>', { text: url, href: url }));
               };
         

Result (interactive)

Publishers

Pearson

UK

Shueisha

Japan

Wiley

US

Styling Panels

It's straightforward to style your panel navigation with CSS.  See the CSS for the examples below: panel-nav.css

Flat tabs
Example HTML for flat tabs styling

               <h2>Book format</h2>
               <nav class=dna-menu data-nav=book-format data-style=flat-tabs>
                  <span>Hardcover</span>
                  <span>Paperback</span>
                  <span>eBook</span>
               </nav>
               <div class=dna-panels data-nav=book-format>
                  <p>Hardcovers are the nicest.</p>
                  <p>Paperbacks are the easiest.</p>
                  <p>EBooks are the future.</p>
               </div>
         

Result (interactive)

Book format

Hardcovers are the nicest.

Paperbacks are the easiest.

eBooks are the future.

Pillbox tabs
Example HTML for pillbox tabs

               <h2>Book type</h2>
               <nav class=dna-menu data-nav=book-type data-style=pillbox-tabs>
                  <span>Action</span>
                  <span>Mystery</span>
                  <span>Science Fiction</span>
               </nav>
               <div class=dna-panels data-nav=book-type>
                  <p>Action books</p>
                  <p>Mystery books</p>
                  <p>Science fiction books are the best!</p>
               </div>
         

Result (interactive)

Book type

Action books rock!

Mystery books rule!

Science fiction books are the best!

Example website with pillbox UI tabs:
CLABE Validator

Utilities

The utility functions built into dna-engine are available to be called directly in the event that they might be generally useful.

Utility Functions Overview
  1. dna.array.find(array, code)
  2. dna.array.fromMap(map, key)
  3. dna.array.last(array)
  4. dna.array.toMap(array, key)
  5. dna.array.wrap(value)
  6. dna.browser.getUrlParams()
  7. dna.pageToken
    dna.pageToken.get(key, value)
    dna.pageToken.put(key, defaultValue)
  8. dna.ui.deleteElem(elemOrEventOrIndex)
  9. dna.ui.focus(elem)
  10. dna.ui.getAttrs(elem)
  11. dna.ui.getComponent(elem)
  12. dna.ui.pulse(elem, options)
  13. dna.ui.slideFade
    dna.ui.slideFadeDelete(elem)
    dna.ui.slideFadeIn(elem, callback)
    dna.ui.slideFadeOut(elem, callback)
    dna.ui.slideFadeToggle(elem, callback)
  14. dna.ui.smoothHeight
    dna.ui.smoothHeightAnimate(delay, elem)
    dna.ui.smoothHeightSetBaseline(elem)
  15. dna.ui.smoothMove(elem, up)
  16. dna.ui.toElem(elemOrEventOrIndex, that)
  17. dna.util.apply(func, params)
  18. dna.util.assign(data, field, value)
  19. dna.util.getFn(funcName)
  20. dna.util.isObj(value)
  21. dna.util.printf(formatString, parameters...)
  22. dna.util.realTruth(value)
  23. dna.util.toCamel(kebabCaseStr)
  24. dna.util.toKebab(camelCaseStr)
  25. dna.util.value(data, field)

dna.array.find(array, value, key)

Returns the index and a reference to the first array element with a key equal to the supplied value.  The default key is "code".

Parameters:
  • An array of objects.
  • An object, array, or primitive of any value.
  • The name of a field in an object.
Examples

            const things = [
               { code: 'a', word: 'Ant' },
               { code: 'b', word: 'Bat' }
               ];
            const x = dna.array.find(things, 'b');  //{ index: 1, item: { code: 'b', word: 'Bat' } }
            const y = dna.array.find(things, 'b').index;  //1
            const z = dna.array.find(things, 'x');  //{ index: -1, item: null }
         

dna.array.fromMap(object, key)

Converts an object (hash map) into an array of objects.  The default key is "code".

Parameters:
  • An object literal.
  • The name of a field in an object.
Examples

            const map = {
               a: { word: 'Ant' },
               b: { word: 'Bat' }
               };
            const array = dna.array.fromMap(map);
            // New array:
            //    [{ code: 'a', word: 'Ant' }, { code: 'b', word: 'Bat' }]
         

dna.array.last(array)

Returns the last element of the array (or undefined if not possible).

Parameters:
  • An array.
Examples

            dna.array.last([3, 21, 7]) === 7;  //true
         

dna.array.toMap(array, key)

Converts an array of objects into an object (hash map).  The default key is "code".

Parameters:
  • An array of objects.
  • The name of a field in an object.
Examples

            const words = [
               { code: 'a', word: 'Ant' },
               { code: 'b', word: 'Bat' }
               ];
            const wordMap = dna.array.toMap(words);
            // wordMap:
            //    { a: { code: 'a', word: 'Ant' }, b: { code: 'b', word: 'Bat' } }
         

dna.array.wrap(value)

Always returns an array.

Parameters:
  • An object, array, or primitive of any value.
Examples

            dna.array.wrap('hello');       //['hello']
            dna.array.wrap([3, null, 7]);  //[3, null, 7]
            dna.array.wrap();              //[]
            dna.array.wrap(null);          //[]
         

dna.browser.getUrlParams()

Returns the query parameters as an object literal.

dna.pageToken.get(key, defaultValue)

dna.pageToken.put(key, value)

A simple key/value store specific to the page (URL path) that is cleared out when the user's browser session ends.

Parameters:
  • Identifier to lookup data.
  • Data to store.
  • Data to return if the page token is not found.
Example using a direct function call

            const a = dna.pageToken.get('favorite', 0);  //a === 0
            dna.pageToken.put('favorite', 7);
            const b = dna.pageToken.get('favorite', 0);  //b === 7
         

dna.ui.deleteElem(elemOrEventOrIndex)

A flexible function for removing a jQuery element.

Parameters:
  • Reference to a jQuery element.
Example 1: Direct function call

            dna.ui.deleteElem($('.box:first'));  //removes first box
         
Example 2: jQuery callback

            $('.box:last').fadeOut(dna.ui.deleteElem);  //removes last box
         

dna.ui.focus(elem)

Sets focus on an element.

Parameters:
  • An element.
Example HTML

            <label>
               <span>Start typing:</span>
               <input data-on-load=dna.ui.focus>
            </label>
         

dna.ui.getAttrs(elem)

Returns the attributes of the DOM node in a regular array.

Parameters:
  • An element.

dna.ui.getComponent(elem)

Returns the component (container element with a data-component attribute) to which the element belongs.

Parameters:
  • An element.

dna.ui.pulse(elem[, options])

Fades in an element after hiding it to create a single smooth flash effect.  If the element is initially hidden, it will slide down.

Parameters:
  • Any element within the clone or even the clone itself.
    • Milliseconds for the fade in animation to run (default: 400).
    • How long the element will remain visible before starting fading out (default: null for no fade out).
    • Milliseconds for the fade out animation to run (default: 5000).
Example JavaScript

            dna.ui.pulse($('#msg').text('Error!'));  //simple flash effect
         
Example JavaScript

            const elem = $('#msg').text('Error!');
            const options = { interval: 7000, out: 2000 };
            dna.ui.pulse(elem, options);  //show for 7 seconds then slowly fade
         

This UI function is primarily intended to display a status or error message.

dna.ui.slideFadeDelete(elem)

dna.ui.slideFadeIn(elem[, callback])

dna.ui.slideFadeOut(elem[, callback])

dna.ui.slideFadeToggle(elem[, callback])

Various functions to apply the smooth slide plus fade effect.

Parameters:
  • Any element within the clone or even the clone itself.
  • String name of a function or an actual function.
Example JavaScript

            dna.ui.slideFadeDelete($('.box').last());  //removes the last box
            dna.ui.slideFadeIn($('.box').first());  //shows the box
         

dna.ui.smoothHeightSetBaseline([elem])

dna.ui.smoothHeightAnimate([delay, [elem]])

Smoothly animates the height of a container element from a beginning height to a final height.

If no container element (elem) is specified, the <body> element will be used for the baseline and the animation will use the previously set baseline.

The animation start delay (default is 50 milliseconds) allows time for the container to be drawn.

Usage steps:
  1. Call dna.ui.smoothHeightSetBaseline() to establish the initial height of the container.
  2. Insert (show) and remove (hide) multiple elements within the container.
  3. Call dna.ui.smoothHeightAnimate() to smoothly adjust the container element to its new height.
Parameters:
  • An element.
  • Time in milliseconds to wait before performing operation.
Smooth container of chapters

            Number of chapters:<br>
            <input type=range value=10
               data-on-load=makeChapters data-change=smooth>
            <div id=smooth-container>
               <button id=chapter-box class=dna-template>~~[count]~~</button>
            </div>
            <script>
               const makeChapters = (range) => {
                  const options = { empty: true, clones: +range.val() };
                  dna.clone('chapter-box', {}, options);
                  };
               const smooth = (range) => {
                  dna.ui.smoothHeightSetBaseline($('#smooth-container'));
                  makeChapters(range);
                  dna.ui.smoothHeightAnimate();
                  };
            </script>
         

Result (interactive)
Number of chapters:

dna.ui.smoothMove(elem, up)

Uses animation to smoothly slide an element up or down one slot amongst its siblings.

Parameters:
  • Any element within the clone or even the clone itself.
  • Direction to move element is up (true) or down (false).
Example

            <ol>
               <li>The DOM</li>
               <li id=favorite>Go JavaScript!</li>
               <li>Styling CSS3</li>
            </ol>
            <script>dna.ui.smoothMove($('#favorite'), true);</script>
         

The book Go JavaScript! will be first on the list after smoothMove() has executed.

dna.ui.toElem(elemOrEventOrIndex, that)

A flexible way to get the jQuery element whether it is passed in directly, the target of an event, or comes from the jQuery context.

Parameters:
  • Reference to a jQuery element.
  • this.
Example JavaScript

            function logFadeDone(e) {
               console.log('Element faded out:', dna.ui.toElem(e, this));
               }
            $('.box').last().fadeOut(logFadeDone);
         

dna.util.apply(func, params)

Calls a function passing in the provided parameters.

Parameters:
  • String name of a function or an actual function.
  • A single value to pass into the function or an array of values where each element in the array is a parameter passed into the function.
Example JavaScript

            dna.util.apply('app.cart.buy', 7);      //app.cart.buy(7);
            dna.util.apply(Math.max, [7, 21, -3]);  //21;
            dna.util.apply('fadeIn', $('h1'));      //$('h1').fadeIn();
            dna.util.apply('css', [$('h1'), { color: 'red' }]);
            dna.util.apply('css', [$('h1'), 'color', 'gold']);
         

dna.util.assign(data, field, value)

Sets the field in the data object to the new value and returns the updated data object.

Parameters:
  • Object with fields containing data.
  • Name of a field within the data object (supports object dot notation for nested objects).
  • An object, array, or primitive of any value.
Example JavaScript

            const data = { cart: { items: 7 } };
            dna.util.assign(data, 'cart.items', 8);
            // New data: { cart: { items: 8 } }
         

Note: See dna.util.value() for the complementary action of reading a field value from an object.

dna.util.getFn(funcName)

Converts a dot notation name (string) to its callable function.

Parameters:
  • Name of a function. Supports dot notation strings.
Example JavaScript

            const buyFn = dna.util.getFn('app.cart.buy');
            buyFn(7);  //equivalent to executing: app.cart.buy(7);
         

dna.util.isObj(value)

Determines if something is a real object and not a primitive or array.

Parameters:
  • An object, array, or primitive of any value.
Example JavaScript

            return dna.util.isObj(it) ? it : { value: it };  //always returns an object
         

dna.util.printf(formatString, args...)

Builds a formatted string by replacing the format specifiers with the supplied arguments.

Parameters:
  • String with format specifiers ('%s') indicating where arguments are to be inserted.
  • Arguments used to replace format specifiers.
Example JavaScript

            dna.util.printf('%s: %s', 'Lives', 3);  //'Lives: 3'
         

dna.util.realTruth(value)

Returns the "real" boolean truth of a value.  Whereas JavaScript truthy and falsey are more about existence, the "real" truth is for evaluating boolean data as it is stored in databases or transmitted in REST calls.

Parameters:
  • An object, array, or primitive of any value.
Example JavaScript

            dna.util.realTruth('F');  //false
         

dna.util.toCamel(kebabCaseStr)

Converts a kebab-case string (a code made of lowercase letters and dashes) to camelCase.

Parameters:
  • A string made of lowercase letters and dashes.
Example JavaScript

            dna.util.toCamel('ready-set-go');  //'readySetGo'
         

dna.util.toKebab(camelCaseStr)

Converts a camelCase string to kebab-case (a code made of lowercase letters and dashes).

Parameters:
  • A camelCase string.
Example JavaScript

            dna.util.toKebab('readySetGo');  //'ready-set-go'
         

dna.util.value(data, field)

Returns the value of the field from the data object.

Parameters:
  • Object with fields containing data.
  • Name of a field within the data object (supports object dot notation for nested objects).
Example JavaScript

            const data = { cart: { items: 7 } };
            const count = dna.util.value(data, 'cart.items');  //7
         

Note: See dna.util.assign() for the complementary action of setting a value in an object.

Index

List of Classes

  1. dna-hide: Hides a container element until a descendant template is cloned
  2. dna-menu: Mark element as container for panel menu items
  3. dna-panels: Mark element as container for panels
  4. dna-separator: Mark element as a separator for multiple clones
  5. dna-separator-last: Mark element as the last separator
  6. dna-template: Mark an element as a template

List of Data Attributes

  1. data-array: Mark an element as a sub-template array loop
  2. data-attr-{NAME}: Set value of an element attribute
  3. data-callback: Pass element into function when clone is created
  4. data-change: Callback to run on change event
  5. data-class: Add a class to the element
  6. data-click: Callback to run on click event
  7. data-component: Mark a container element as a component
  8. data-enter-key: Callback to run on enter key event
  9. data-false: Show element only if field evaluates to false
  10. data-focus-in: Callback to run when an element receives focus
  11. data-focus-out: Callback to run when an element loses focus
  12. data-format-{TYPE}: Format a value for proper rendering
  13. data-format: Custom format function
  14. data-hash: Set the fragment ID (hash) for a panel's URL
  15. data-hover-in: Callback to run on mouse enter event
  16. data-hover-out: Callback to run on mouse leave event
  17. data-href: Jumps to the URL (like an <a> link)
  18. data-input: Callback to run on input event
  19. data-key-down: Callback to run on key down event
  20. data-key-press: Callback to run on key press event
  21. data-key-up: Callback to run on key up event
  22. data-last-separator: Insert text, like a comma, between clones
  23. data-missing: Show element only if field does not exist
  24. data-on-load: Pass element into function after HTML is loaded
  25. data-option: Set option in a select drop-down
  26. data-placeholder: Show element only if named template is empty
  27. data-prop-checked: Enable or disable "checked" property
  28. data-prop-disabled: Enable or disable "disabled" property
  29. data-prop-selected: Enable or disable "selected" property
  30. data-require: Show element only if field exists
  31. data-separator: Insert text between the last two clones
  32. data-smart-throttle: Delay (milliseconds) between smart update callbacks
  33. data-smart-update: Throttled callback to run on change of an input value
  34. data-transform: Callback to enhance data immediately before cloning
  35. data-true: Show element only if field evaluates to true
  36. data-wait-for: Specify optional dependencies for data-on-load

List of jQuery Plugin Functions

  1. .dna('bye'): Slide fade out then remove
  2. .dna('clone-sub', name, data[, options]): Clone a sub-template
  3. .dna('destroy'[, options]): Remove
  4. .dna('down'): Smoothly move down one slot
  5. .dna('refresh'[, options]): Update to reflect changes to the data model
  6. .dna('up'): Smoothly move up one slot

List of jsFiddle Examples

ExampleLink
Add a Book jsfiddle.net/Lv4pjt0g/1
Book Finder jsfiddle.net/r8hwk0Lq/1
Click Events jsfiddle.net/50gwncj3/1
Live Model jsfiddle.net/xez27s0o/1
Panels Click jsfiddle.net/m7b9h53a/1
Panels Drop-downjsfiddle.net/rdjb6cka/2
Photo Upload jsfiddle.net/o5p0wjd1/1
Smart Updates jsfiddle.net/a5rsLcb2/1
To Do jsfiddle.net/3qbkjguy/1

Questions and comments

Questions and comments

Tweet your question or comment with #dna-engine or submit an issue on GitHub.