Run Time Templating

We use run-time templating in order to separate markup (i.e. HTML) from code (i.e. JavaScript or Java). The idea is that when we're writing HTML/CSS code, we should have to worry about how the JavaScript is going to inject our markup into the document. Similarly, when we're writing JavaScript, we shouldn't have to worry about exactly what markup we're injecting.

To that end, we had the following design goals in mind when making the templating engine:

• That it compile into both JavaScript and Java
• That it have enough features so that the template files could fully express any markup the developer needs
• That it not have so many features that developers were tempted to put complex code into the template files

Syntax for defining templates

Each template has two files associated to it: a .tmplt (pronounced "template") file and a .tspec (pronounced "t-spec", or "template specification") file. The .tspec file defines the variables used in the template. The .tmplt file defines the actual output of the file.

.tspec files consist of a series of declarations. Declarations can be formatted in any of the following ways:

@param varName
@param {type} varName
@param varName {type}
@param varName comment
@param {type} varName comment
@param varName {type} comment

The type is only used for the java output. If no type is specified, the type Object is used. The comments can be as many lines as desired. Any line which does not start with @param will be assumed to be part of a comment.

The .tmplt contains the contents of what the output from the template should look like. However, expressions can be evaluated in the .tmplt file by using the syntax {{expr}}. So, for instance, if your .tspec file was:

@param title The title for a button

And your .tmplt file was:

	<button>{{title}}</button>

Then runing the template with the parameter Click Me would result in:

	<button>Click Me</button>

However, expressions can be more complicated. For instance, if you had a .tspec file:

@param {int} x
@param {int} y

And a .tmplt file:

	<p>Did you know that {{x}} + {{y}} = {{x+y}}?</p>

Then if you used the parameters 1 and 2 you would get:

	<p>Did you know that 1 + 2 = 3?</p>

Not that it was important to specify the types for x and y, or else the java output would have thrown an error (since you can't add variables of type Object). You can also use ternary statements. For instance, if you had a .tspec file:

@param {boolean} loggedIn

And a .tmplt file:

	<a>
		{{ (loggedIn ? }}
			Sign In
		{{ : }}
			Sign Out
		{{ ) }}
	</a>

Note the use of parentheses. If you didn't use parentheses, the templating engine would have tried to evaluate loggedIn ? or : on their own without the larger context that they are part of one, continuous, larger expression. This would have thrown an error.

Syntax for running the templates

Suppose you had a template button. In javascript, this template could be invoked via a command templates.button(param1, param2, ...). In java, you would first have to import the Button class and then use Button.run(param1, param2, ...) to run the template.