Domplate

From FirebugWiki

(Difference between revisions)
Jump to: navigation, search
(Added some examples borrowed from Honza's website)
(Hello World!)
(3 intermediate revisions not shown)
Line 12: Line 12:
* User-defined callbacks to iterate and format data
* User-defined callbacks to iterate and format data
* Object oriented design allows for advanced hierarchies  
* Object oriented design allows for advanced hierarchies  
 +
 +
== API ==
 +
 +
=== Constructor attribute naming rules ===
 +
 +
There are some rules for constructor attribute names. See the following list with all existing rules:
 +
* '''Name begins with "on":''' value of this attribute must be a function, which is used as an event handler for the specified event
 +
* '''Name begins with "_":''' a new property is created on this DOM element ("_" isn't part of the result property name) with appropriate value
 +
* '''Name begins with "$":''' if actual value of the attribute is true (boolean) a new class with the same name (without "$") is inserted into the class attribute of the DOM element.
== Examples ==
== Examples ==
Line 20: Line 29:
The very first example shows basic steps you need to do to define and execute a template.
The very first example shows basic steps you need to do to define and execute a template.
-
<pre>
+
<source lang="javascript">
var template = domplate(
var template = domplate(
{
{
Line 28: Line 37:
template.tag.replace({}, parentNode, template);
template.tag.replace({}, parentNode, template);
-
</pre>
+
</source>
-
Notice that the template is created with the <code>domplate<code> function and contains one <code>tag</code> definition. The tag consists of one <code>DIV</code> constructor (a function).
+
Notice that the template is created with the <code>domplate</code> function and contains one <code>tag</code> definition. The tag consists of one <code>DIV</code> constructor (a function).
In order to execute the template, the example uses a <code>replace</code> method (there are other methods yet) and passes an input object (empty in this case), parent DOM node (where the result should be inserted) and scope object (the template itself) into it.
In order to execute the template, the example uses a <code>replace</code> method (there are other methods yet) and passes an input object (empty in this case), parent DOM node (where the result should be inserted) and scope object (the template itself) into it.
Line 37: Line 46:
This example shows how an input object can be used to provide dynamic data for a template.
This example shows how an input object can be used to provide dynamic data for a template.
-
<pre>
+
<source lang="javascript">
var inputObject = {
var inputObject = {
     firstName: "Jan",
     firstName: "Jan",
     lastName: "Odvarko"
     lastName: "Odvarko"
};
};
 +
</source>
 +
<source lang="javascript">
var template = domplate(
var template = domplate(
{
{
Line 56: Line 67:
template.tag.replace({object: inputObject}, parentNode, template);
template.tag.replace({object: inputObject}, parentNode, template);
-
</pre>
+
</source>
The template refers to a property of the input object using a "$" character at the beginning of the property name. Standard dot notation is used to access inner properties. The actual value from the object is used when the template is executed.
The template refers to a property of the input object using a "$" character at the beginning of the property name. Standard dot notation is used to access inner properties. The actual value from the object is used when the template is executed.
Line 64: Line 75:
This example shows how to use a <code>FOR</code> loop and iterate array of input objects.
This example shows how to use a <code>FOR</code> loop and iterate array of input objects.
-
<pre>
+
<source lang="javascript">
var inputArray = ["red", "green", "blue", "white"];
var inputArray = ["red", "green", "blue", "white"];
 +
</source>
 +
<source lang="javascript">
var template = domplate(
var template = domplate(
{
{
Line 76: Line 89:
template.tag.replace({array: inputArray}, parentNode, template);
template.tag.replace({array: inputArray}, parentNode, template);
-
</pre>
+
</source>
A loop is constructed using a <code>FOR</code> constructor, which expects two parameters. The first one defines a variable, which contains the actual value from the array in each cycle and the second one is the array to be iterated.
A loop is constructed using a <code>FOR</code> constructor, which expects two parameters. The first one defines a variable, which contains the actual value from the array in each cycle and the second one is the array to be iterated.
Line 84: Line 97:
This example shows how to register an event handler.
This example shows how to register an event handler.
-
<pre>
+
<source lang="javascript">
var inputArray = ["red", "green", "blue", "white"];
var inputArray = ["red", "green", "blue", "white"];
 +
</source>
 +
<source lang="javascript">
var template = domplate(
var template = domplate(
{
{
Line 105: Line 120:
template.tag.replace({array: inputArray}, parentNode, template);
template.tag.replace({array: inputArray}, parentNode, template);
-
</pre>
+
</source>
The template registers a handler for every generated <code>&lt;div&gt;</code> element, that shows an alert box with the content of the clicked element. Notice that the scope object (which is usually the template itself) is used to execute the <code>handleClick</code> function.
The template registers a handler for every generated <code>&lt;div&gt;</code> element, that shows an alert box with the content of the clicked element. Notice that the scope object (which is usually the template itself) is used to execute the <code>handleClick</code> function.
If the constructor's attribute name begins with "on", it's treated as an event name (without "on") for the correspondend DOM event. It's value must always be a function, that is registered as the event listener.
If the constructor's attribute name begins with "on", it's treated as an event name (without "on") for the correspondend DOM event. It's value must always be a function, that is registered as the event listener.
 +
 +
=== How to generate DOM attributes ===
 +
 +
This example shows how to generate HTML attributes.
 +
 +
<source lang="css">
 +
.green {
 +
    color: green;
 +
}
 +
</source>
 +
 +
<source lang="javascript">
 +
var inputObject = {
 +
    label: "Click Me!",
 +
};
 +
</source>
 +
 +
<source lang="javascript">
 +
var template = domplate(
 +
{
 +
    tag:
 +
      BUTTON({class: "green",
 +
              checked: "true",
 +
              type: "checkbox",
 +
              onclick: "$onButtonClick"},
 +
          "$object.label"
 +
        ),
 +
 +
    onButtonClick: function(event)
 +
    {
 +
        alert("Hello World!");
 +
    }
 +
});
 +
 +
template.tag.replace({object: inputObject}, parentNode, template);
 +
</source>
 +
 +
Attributes are defined as members of an object, that is passed as the first
 +
parameter to the <code>BUTTON</code> constructor.
 +
 +
=== How to reuse an existing template ===
 +
 +
This example shows how to use the <code>TAG</code> constructor in order to reuse an existing template.
 +
 +
<source lang="javascript">
 +
var template = domplate(
 +
{
 +
    tag:
 +
        DIV(
 +
            TAG("$anotherTag")
 +
        ),
 +
 +
    anotherTag:
 +
        SPAN("Embedded Tag"),
 +
});
 +
 +
template.tag.replace({}, parentNode, template);
 +
</source>
 +
 +
An existing tag can be simply referenced through a <code>TAG</code> constructor.
 +
 +
=== How to pass data into aggregated template ===
 +
 +
See another example of tag reusing, that also shows how to pass data into an embedded template.
 +
 +
<source lang="javascript">
 +
var inputArray = ["Honza", "Radek", "John", "Mike"];
 +
</source>
 +
 +
<source lang="javascript">
 +
var template = domplate(
 +
{
 +
    table:
 +
        TABLE({border: "1", width: "100px"},
 +
            FOR("item", "array",
 +
                TAG("$row", {name: "$item"})
 +
            )
 +
        ),
 +
 +
    row:
 +
        TR({align: "center"},
 +
            TD("$name")
 +
        )
 +
});
 +
 +
template.table.replace({array: inputArray}, parentNode, template);
 +
</source>
 +
 +
You can see that input object is passed into the embedded <code>TAG</code> as a second parameter.
 +
 +
=== How to set DOM properties ===
 +
 +
This example shows how to set a new property on a generated DOM object.
 +
 +
<source lang="javascript">
 +
var cars = [
 +
  {name: "Honda Pilot", price: " $36,820 - $49,920"},
 +
  {name: "Chevrolet Aveo", price: "$13,270 - $15,770"},
 +
  {name: "Toyota Corolla", price: " $14,835 - $23,480"}
 +
];
 +
</source>
 +
 +
<source lang="javascript">
 +
var template = domplate(
 +
{
 +
    tag:
 +
        FOR("item", "array",
 +
            DIV({_myprop: "$item", onclick: "$onClick"},
 +
                "$item.name"
 +
            )
 +
        ),
 +
 +
    onClick: function(event)
 +
    {
 +
        var car = event.target.myprop;
 +
        alert(car.price);
 +
    }
 +
});
 +
 +
template.tag.replace({array: cars}, parentNode, template);
 +
</source>
 +
 +
If the constructor's attribute name begins with "_", it's always treated as a DOM property. '''Notice that the name of created property is without "_".'''
== Links ==
== Links ==

Revision as of 23:20, 31 March 2013

Domplate is a JavaScript template system. It allows you to speed up UI development by offering special functions for creating HTML elements and event handlers bound to it.

Domplate basically consists of three parts:

  • Domplate Script: the script used to describe the Domplate template
  • Input Data (object): input data for a dynamic template
  • CSS: set of CSS rules used by result DOM

To try out Domplate you can use the Domplate Runner written by Jan "Honza" Odvarko. He also wrote some tutorials about Domplate available at his website. Also Christoph Dorn gives an introspective into Domplate at his blog.

Contents

Features

  • Templates are assembled via function calls instead of strings
  • User-defined callbacks to iterate and format data
  • Object oriented design allows for advanced hierarchies

API

Constructor attribute naming rules

There are some rules for constructor attribute names. See the following list with all existing rules:

  • Name begins with "on": value of this attribute must be a function, which is used as an event handler for the specified event
  • Name begins with "_": a new property is created on this DOM element ("_" isn't part of the result property name) with appropriate value
  • Name begins with "$": if actual value of the attribute is true (boolean) a new class with the same name (without "$") is inserted into the class attribute of the DOM element.

Examples

The examples listed here should give you a point were to start at. For more examples please visit Jan Odvarko's website.

Hello World!

The very first example shows basic steps you need to do to define and execute a template.

var template = domplate(
{
    tag:
        DIV("Hello World!"),
});
 
template.tag.replace({}, parentNode, template);

Notice that the template is created with the domplate function and contains one tag definition. The tag consists of one DIV constructor (a function). In order to execute the template, the example uses a replace method (there are other methods yet) and passes an input object (empty in this case), parent DOM node (where the result should be inserted) and scope object (the template itself) into it.

How to use input data

This example shows how an input object can be used to provide dynamic data for a template.

var inputObject = {
    firstName: "Jan",
    lastName: "Odvarko"
};
var template = domplate(
{
    tag:
        DIV(
            SPAN("First Name: "),
            SPAN("$object.firstName"),
            BR(),
            SPAN("Last Name: "),
            SPAN("$object.lastName")
        )
});
 
template.tag.replace({object: inputObject}, parentNode, template);

The template refers to a property of the input object using a "$" character at the beginning of the property name. Standard dot notation is used to access inner properties. The actual value from the object is used when the template is executed.

How to construct a FOR Loop

This example shows how to use a FOR loop and iterate array of input objects.

var inputArray = ["red", "green", "blue", "white"];
var template = domplate(
{
    tag:
        FOR("item", "$array",
           DIV("$item")
        )
});
 
template.tag.replace({array: inputArray}, parentNode, template);

A loop is constructed using a FOR constructor, which expects two parameters. The first one defines a variable, which contains the actual value from the array in each cycle and the second one is the array to be iterated.

How to handle a DOM event

This example shows how to register an event handler.

var inputArray = ["red", "green", "blue", "white"];
var template = domplate(
{
    tag:
        FOR("item", "$array",
            DIV({onclick: "$handleClick"},
 
               "$item"
            )
        ),
 
    handleClick: function(event)
    {
 
        alert(event.target.innerHTML);
    }
});
 
template.tag.replace({array: inputArray}, parentNode, template);

The template registers a handler for every generated <div> element, that shows an alert box with the content of the clicked element. Notice that the scope object (which is usually the template itself) is used to execute the handleClick function.

If the constructor's attribute name begins with "on", it's treated as an event name (without "on") for the correspondend DOM event. It's value must always be a function, that is registered as the event listener.

How to generate DOM attributes

This example shows how to generate HTML attributes.

.green {
    color: green;
}
var inputObject = {
    label: "Click Me!",
};
var template = domplate(
{
    tag:
       BUTTON({class: "green",
              checked: "true",
              type: "checkbox",
              onclick: "$onButtonClick"},
           "$object.label"
        ),
 
    onButtonClick: function(event)
    {
        alert("Hello World!");
    }
});
 
template.tag.replace({object: inputObject}, parentNode, template);

Attributes are defined as members of an object, that is passed as the first parameter to the BUTTON constructor.

How to reuse an existing template

This example shows how to use the TAG constructor in order to reuse an existing template.

var template = domplate(
{
    tag:
        DIV(
            TAG("$anotherTag")
        ),
 
    anotherTag:
        SPAN("Embedded Tag"),
});
 
template.tag.replace({}, parentNode, template);

An existing tag can be simply referenced through a TAG constructor.

How to pass data into aggregated template

See another example of tag reusing, that also shows how to pass data into an embedded template.

var inputArray = ["Honza", "Radek", "John", "Mike"];
var template = domplate(
{
    table:
        TABLE({border: "1", width: "100px"},
            FOR("item", "array",
                TAG("$row", {name: "$item"})
            )
        ),
 
    row:
        TR({align: "center"},
            TD("$name")
        )
});
 
template.table.replace({array: inputArray}, parentNode, template);

You can see that input object is passed into the embedded TAG as a second parameter.

How to set DOM properties

This example shows how to set a new property on a generated DOM object.

var cars = [
  {name: "Honda Pilot", price: " $36,820 - $49,920"},
  {name: "Chevrolet Aveo", price: "$13,270 - $15,770"},
  {name: "Toyota Corolla", price: " $14,835 - $23,480"}
];
var template = domplate(
{
    tag:
        FOR("item", "array",
            DIV({_myprop: "$item", onclick: "$onClick"},
                "$item.name"
            )
        ),
 
    onClick: function(event)
    {
        var car = event.target.myprop;
        alert(car.price);
    }
});
 
template.tag.replace({array: cars}, parentNode, template);

If the constructor's attribute name begins with "_", it's always treated as a DOM property. Notice that the name of created property is without "_".

Links

Personal tools