Home

What is HTMLSplicer?

HTMLSplicer is a toolkit that provides methods to generate complex HTML documents from simpler HTML documents, called templates. This toolkit can be used to generate servlet responses in Java web-applications.

HTMLSplicer is an alternative to presentation-layer frameworks such as JSP, Apache Velocity, Apache Wicket or GWT. Instead of imposing a common platform/methodology to build the client and server sides of web-applications, HTMLSplicer offers a simple bridge between HTML and Java worlds.

In this approach, the development of the HTML, Javascript and CSS is left to client-side developers and their tools. Server-side developers can use a basic servlet engine for session management, request handling and response creation. When generating the response, the servlet can use HTMLSplicer to construct the response from static HTML templates developed by the client-side technology team, and dynamic HTML generated on the fly at the server.

The end-result is that client-side and server-side development can happen largely independent of each other, provided that there is agreement on the structure of HTTP requests, and "splicing" operations needed to generate responses.

Read more at: [Disadvantages of using presentation-layer frameworks]

Installation

HTMLSplicer is one JAR file with no dependencies. You can add it to you application's classpath.

If you use Maven, you can add HTMLSplicer using this dependency

<dependency>
  <groupId>com.lambdazen.htmlsplicer</groupId>
  <artifactId>htmlsplicer</artifactId>
  <version>0.5</version>
</dependency>

The project artifacts are hosted in the Sonatype OSS Maven Repository at https://oss.sonatype.org/content/groups/public/. You can add this to your pom.xml or settings.xml by following these instructions

HTML templates

The goal behind the design of HTMLSplicer is to keep most of the HTML code delivered by a web-application as static HTML files. These static HTML files are valid, fully-functional documents that are developed, tested and maintained in conjunction with supporting Javascript and CSS files. These HTML files can be turned into HTML templates by adding the following attributes:

bind: The bind attribute indicates that the contents that go inside this tag are 'bound' to a variable named after the attribute value. For example,

<p bind="foo">Something <b>bold</b></p>

means that the variable 'foo' refers to 'Something <b>bold</b>'.

sub: The sub attribute, short for substitute, indicates that the contents of this tag must be substituted by a variable matching the attribute value. For example,

<span sub="foo">Something that will be <i>replaced</i></span> 

means that the contents of the 'span' tag must be replaced with a variable named 'foo'.

ins: The ins attribute, short for insert, indicates that the contents of this tag can be repeatedly inserted with a variable matching the attribute value. For example,

<ol ins="list.item"></ol> 

indicates that a variable named 'list.item' can be inserted multiple times into the <ol> tag.

More on this at [HTML templates]

Loading templates into Java

The two key classes in HTMLSplicer are TemplateBuilder and HTMLTemplate.

TemplateBuilder helps create instances of HTML templates, modeled by the class HTMLTemplate, from org.w3c.dom.Document objects. You can use validator.nu from http://about.validator.nu/htmlparser/ or an alternative DOM parser to parse the files, strings and resources into DOM Documents.

Dynamic content can be fed to the TemplateBuilder as DOM objects that are either created directly using the DOM API, or parsed from a dynamically generated string.

Read more at [Loading HTML templates]

Operations on HTML templates

HTMLTemplate objects support methods to construct other HTMLTemplates using "splicing" operations. The three major "splicing" operations are described (at a high-level) below.

sub(list of input templates): The sub operation looks at the 'sub' attributes in the current HTML template and replaces these tags with the contents of the corresponding 'bind' tags in the input list of HTML templates. The result of the operation is a new HTMLTemplate with these substitutions.

ins(prefix, list of other templates): The ins operation looks at the 'ins' attributes in the current HTML template that start with the given prefix followed by a '.', and inserts the contents of corresponding 'bind' tags in the input list of HTML templates (without the prefix). The result of the operation is a HTML template with these insertions.

insComplete(): Indicates that all inserts are complete for this HTML template.

For example, A.ins("list", B).ins("list", C).insComplete() where

A = <ol type="i" ins="list.item"><li>Will be removed</li></ol>
B = <ol type="A" bind="item"><li>Item 1</li></ol> 
C = <ul bind="item"><li><i>Item 2</i></li><li><i>Item 3</i></li></ul>

will result in

<ol type="i"><li>Item 1</li><li><i>Item 2</i></li><li><i>Item 3</i></li></ol>

The class HTMLTemplate also supports two methods to extract the final document

getDocument: Returns the DOM Document after validating that all mandatory substitutions and insertions have been made.

getDocument(URI baseURL): Same as getDocument(), except that all href and src tags are changed to baseURL.resolve(attribute value). This is useful when the static css and js resources are hosted in a different domain or path than expected by the original source file.

Read more at [Operations on HTML templates]

A quick example

Consider the following HTML templates:

1. Template siteLayout has 3 sub tags, viz. header, content and footer. See [http://jsfiddle.net/lambdazen/PhSrw/]

2. Template headerAndFooter defines the header and footer using bind tags. See [http://jsfiddle.net/lambdazen/4CaXT/]

3. Template staticContent defines the content using a bind tag. See [http://jsfiddle.net/lambdazen/ZCZxx/]

Now, if we assign

Document siteOutput = siteLayout.sub(headerAndFooter, staticContent).getDocument();

the object siteOutput will look like [http://jsfiddle.net/lambdazen/ACwhd/]

To make the site content dynamic, you can covert it to a template with substitutions for 'actor' and insertion for 'movie.row'. See [http://jsfiddle.net/lambdazen/q3UE8/]

Let's refer to this template as contentLayout. The sub and ins tags declared in this template can be replaced by dynamically-generated HTMLTemplate objects from DOM nodes such as

actor = <span bind="actor">Robert De Niro</span>
movie1 = <tbody bind="row"><tr><td>Raging Bull</td> <td>Jake </td> <td>1980</td></tr></tbody>
...
movie5 = <tbody bind="row"><tr><td>Cape Fear</td> <td>Max </td> <td>1991</td></tr></tbody>

Now, we can compose a

HTMLTemplate dynamicContent = contentLayout.sub(actor)
                                           .ins("row", movie1)
                                           ...
                                           .ins("row", movie5)
                                           .insComplete();

which will look like [http://jsfiddle.net/lambdazen/jfxbN/]. The object dynamicContent can be used in the place of staticContent to create a dynamic siteOutput.

In this manner, a complex HTML response can be composed through a series of sub on ins operations on static and dynamically-generated HTML templates.

Closing Thoughts

• [Sample architecture with HTMLSplicer] describes how I'm using this tool.
• The source code (under 1000 lines of code) can be downloaded and built using Maven.
• There are unit-tests under src/test, that show how to use HTMLSplicer with the validator.nu parser. WikiExamplesTest.java performs the splicing operations shown in the examples section.
• I appreciate your feedback. Please feel free to report bugs and contribute fixes/features.