HTML templates

This page describes the complete syntax and associated semantics of HTML templates. A HTML template is any valid HTML document with the following additional attributes that can be placed in any HTML element:
1. bind
2. sub
3. ins
4. removeTag

The following sections describe each attribute.

bind

The value of bind attribute is a variable name, which can be any valid HTML attribute. The associated semantics is that this variable refers to, or is bound to, the contents of the children of this element.

Here are some examples of elements with a bind attribute:

Example 1: 
  <span bind="author">Kautilya</span>
~~~~~~

The above example shows a variable named 'author' bound to the text node 'Kautilya'.

~~~~
Example 2: 
  <h1 bind="i18n.welcome"><em>Bienvenue</em></h1>
~~~~

The above example shows a variable named 'i18n.fr.welcome' bound to '&lt;em&gt;Bienvenue&lt;/em&gt;'. 

Example 3:

Mon 11:00	Math 101
Mon 12:00	Lunch

The above example shows a variable 'timetable.mon' bound to the following sequence of DOM nodes:

* Whitespace after <table>

* The two <tr> nodes and their descendants

* Whitespace before </table>

As you can see the binding of a variable is to the list of child nodes under the element, but not the element itself. 

sub
---

The value of a sub attribute is a variable name followed by an optional '?'. The associated semantics is as follows: 

* If there is no trailing '?', this element MUST be substituted with the binding of a matching variable to be a valid document. 

* If there is a trailing '?', this element MAY be substituted with the binding of a matching variable. If this substitution does not take place, the current contents of the element will be used as present.

Here are some examples of elements with the sub attribute: 

Example 4:
Insert the author name here

This must be replaced the by a variable named 'author' for the template to be a valid document. If we use the binding from Example 1, the substitution will yield '<td>Kautilya</td>. 

Note that the sub attribute is removed at the end of a substitution. 

Example 5:

Welcome

The above example shows a sub attribute with a '?', which indicates that the substitution is optional. If we use the binding from example 2 for a substitution, we will get <h1><em>Bienvenue</em></h1>. 

If we don't make the substitution till the end, i.e., till getDocument() is called on the HTML template, we will get <h1><em>Welcome</em></h1>. Note that the sub attribute is removed in either case. 

The above example also includes a bind attribute to the variable 'heading'. This means that the contents of the <h1> tag are also bound to a new variable named 'heading'. This can be used to substitute a different sub/ins element. 

Example 6:

The above example shows a table whose contents must be substituted with a variable named 'timetable.mon', with something like Example 3.  

ins
---

The value of the ins attribute is a variable name followed by an optional '?'. The associated semantics is as follows: 

* If there is no trailing '?', this element MUST be inserted one or more times with the binding of a matching variable to be a valid document. 

* If there is a trailing '?', this element CAN be inserted one or more times with the binding of a matching variable. If this insertion does not take place, the current contents of the element *will be deleted*. 

Here are some examples of elements with the ins attribute: 

Example 7:
Insert the author name here

This must be inserted one or more times with a variable named 'author'. If this tag is inserted twice using Example 1, we will get <td>KautilyaKautilya</td>

Example 8:

A time slot

Some course name

If this tag is inserted once using Example 3, we will get

~~~~~~
  <table class="tt" ins="timetable.mon?">
    <tr><td>Mon 11:00 <td>Math 101 
    <tr><td>Mon 12:00 <td>Lunch
  </table>

If we do another insert using the following template,

  <table class="tt" bind="timetable.mon">
    <tr><td>Mon 13:00 <td>Physics 101
    <tr><td>Mon 14:30 <td>Biology 101
  </table>

the final document will have:

  <table class="tt">
    <tr><td>Mon 11:00 <td>Math 101 
    <tr><td>Mon 12:00 <td>Lunch
    <tr><td>Mon 13:00 <td>Physics 101
    <tr><td>Mon 14:30 <td>Biology 101
  </table>
~~~~~

Note that because the ins tag has a '?' at the end, if no insert was done for this tag, the final document will have an empty table like this:

~~~~~~

removeTag

The removeTag attribute is valid for sub and ins tags, and must be set to either "yes" or "true". The associated semantics is that the final document after the substitutions and insertions are complete will not include this tag. Instead the child elements of this tag will directly appear under the tag's parent node.

Example 9:
  Books by <span sub="author?" removeTag="true">the author</span>

The above example shows a substitution with a removeTag. If we use the binding from Example 1, the substitution will yield 'Books by Kautilya', without the <span> tag. If the substitution is not done, the final result will be 'Books by the author'.

Example 10:
  <table>
    <thead ins="timetable.mon" removeTag="yes">
       <tr><th>Insert time</th><th>Insert class</th></tr>
    </thead>
  </table>

The above example shows an ins tag with removeTag. If this tag is inserted once using Example 3, the final document will have:

  <table>
    <tr><td>Mon 11:00 <td>Math 101 
    <tr><td>Mon 12:00 <td>Lunch
  </table>

Note that the <thead> is removed at the end of the operation.