Operations on HTML templates

Once a HTML template is loaded, we can use the following operations to apply various variable bindings to 'sub' and 'ins' tags in the template, and retrieve the final document.

1. sub()

2. ins()

3. insComplete()

4. getDocument()

The complete API documentation is available at http://sourceforge.net/projects/htmlsplicer/files/apidocs.zip.

sub()

The sub() operation has the following two method signatures:

public HTMLTemplate sub(HTMLTemplate... docs) throws HTMLSplicerException

public HTMLTemplate sub(String prefix, HTMLTemplate... subDocs) throws HTMLSplicerException
~~~~

Calling the first method is same as calling the second one with a null prefix. The purpose of the prefix in the sub() operation is to limit the scope of the operation to 'sub' variables with names that start with the prefix followed by a '.'. 

For example, A.sub("foo.bar", B, C) means that *all* 'sub' tags in A that start with 'foo.bar.' will be replaced. So if the object A has three 'sub' variables, viz. 'foo.bar', 'foo.bar.baz' and 'foo.bar.baz.qux', then the operation will replace both 'foo.bar.baz' and 'foo.bar.baz.qux' with variable bindings from B and C. 

Furthermore, when using a prefix, the variable names looked up in the input documents will *not* include the prefix. In the above example, the sub() operation will look for 'baz' and 'baz.qux' in the templates B and C. The first matching binding for these two variables will be used for substitution. The basic rules of substitution are described in the page [HTML templates].

If any binding can not be found in the given inputs, or the global substitutions provided to the TemplateBuilder that created the object (see [Loading HTML templates]), then the sub() operation will check to see if the substitution is optional, i.e., ends with a '?'. Otherwise, it will throw an exception. 

In summary, the sub() method replaces all 'sub' tags that match the given prefix with bindings from the templates provided to the operation or the global substitution templates available in the Template Builder. 

ins()
---

The ins() operation has the following method signature:

public HTMLTemplate ins(String prefix, HTMLTemplate... subDocs) throws HTMLSplicerException;

A prefix is mandatory for the ins operation. All 'ins' tags that start with the given prefix, followed by '.', will be inserted with bindings located in the subDocs, *without the prefix*. All mandatory 'ins' tags with matching names will be inserted in one ins() operation. Optional 'ins' tags, i.e., tags with names ending with '?', will be skipped during the operation if no matching binding is found. 

insComplete()
-------------

The insComplete() operation indicates the end of insertions and has the following method signature: 

public HTMLTemplate insComplete() throws HTMLSplicerException;

This method checks to see if all mandatory 'ins' tags have been called at least once. Otherwise, it throws an exception. 

This method also removes all the ins attributes from tags, so that further ins() operations on templates that "splice in" this template won't affect the tags in this template. For this reason, it is safer to call insComplete() before using the bindings in this template in another sub/ins operation. 

getDocument()
-------------

The getDocument() operation has the following method signatures:

public Document getDocument() throws HTMLSplicerException;

public Document getDocument(URI baseURL) throws HTMLSplicerException;
~~~~~

The first method returns the DOM Document corresponding to the template. It automatically calls insComplete() and makes sure that all 'sub' tags are properly substituted. Otherwise, it throws an exception.

The second method does the same as getDocument(). But in addition it goes over all the href and src attributes in the returned Document and resolves it against the baseURI provided. This method allows the client-side team to design the HTML assuming that referenced images, css and Javascripts are in the same path as the HTML (like images/foo.jpg or css/jquery/jquery.js). The servlet can use a relative path (like ../..) or an absolute path (like /static or http://static.foo.com/project/bar/) base URI to ensure that the links are properly prefixed in the response.