Templates

Templates are parsed strings which replaces specifically delimited tokens for values from a Symbol Table.

Templates are designed to be created once then evaluated multiple times using different or updated Symbol Table instances so different values can be used. The original use case for this class was creating an email body for a monitoring system which would send an email with the details of an event in consistent manner. The details of the event were different (e.g. time, error message, component in error, severity addressee, etc.) and concatenating strings was just to cumbersome. Templates made it easy to create a "template" of the message and populate the Symbol Table with the details of event and let the template fill in the variables using that table.

Templates search for tags delimited by the opening "[#" and the closing "#]" string sequences. The template parser then replaces the tokens within the delimiters with the string values those tokens represent.

If the token is preceded with a "$", then the token is treated as a key to be used to lookup an object in a symbol table. That object's toString() method is called and the returning value placed in the position where the token was found. This is analogous to a variable lookup. If the token is not found in the table or the symbols object returns a null string, then an empty string is returned.

Tokens that are not preceded with a "$" are treated as class tokens when encountered, the parser attempts to create a new instance of that class, calling the new instances toString() method after it's constructor. If the class is not found, a string value of "null" is returned.

If a class token contains the "." character, then special processing will take place. Specifically, if the last token delimited by the "." character in the class token starts with a lowercase alpha character, then that sub-token will be treated as a method name, and the remaining symbols in that tag will be resolved and passed to that method after that method's class is instantiated.

Classes that are created during the parsing of a template string are cached and re-used by the instance of the Template class. This means the template can be effectively initialized by one template string, loading the classes needed for later template parsing operations.

Pre-initialized class references may be placed into the class cache in an effort to give the template visibility into component frameworks. This allows templates to call into generic, sharable facilities such as Data Access Objects (DAO), data repositories, and any other specialized object that is designed to present data in a string format.

Examples

Templates come in handy for configuration files. It is not always known, for example, from where an application may be run. In this case it might be difficult to specify the location of a file:

"source": "/usr/local/cdx/data/purchasing/po_01_02_15.dat"

One solution is to use a template and let variables resolve to the currently set values:

"source": "[#$app.home#]/data/purchasing/po_01_02_15.dat"

Often, it is desirable to just generate dynamic filenames at runtime:

"target": "file://"dailyaudit-[#$YYYY#][#$MM#][#$DD#].dat"

The actual variables in the symbol table will vary based on the version of the toolkit and the components loaded. Components can contribute values to the symbol table based on their operation. For example, the Transform Engine updates the symbol table with the CurrentFrame and LastFrame symbols representing the current frame count and the boolean flag indicating the last frame respectively.

Check the documentation of each component for symbols components may contribute to the transform context.