Templating Docs: Basic Usage
The templating library consists primarily of two components, both of which implement the Template interface; FileTemplate and StringTemplate. The only difference between the two is how each template is initialized - which we'll get into momentarily. Once initialized however, each template type exposes a replace() method which provides an easy and very flexible way of mutating the template and returning the new variable injected content.
Anatomy of a Template
This library treats a Template as an abstract concept - ultimately it is nothing more than a file or a string whose content you would like to reuse by replacing strings instances within the file or string with variables at runtime. This makes the library itself extremely flexible. For instance in the case of the FileTemplate template type, the content with which this object initializes itself can be a file of almost any type / extension / content-type. This means your actual content template can be of type .txt, .xml, .html, or .cfm - just to name a few examples.
Initializing FileTemplate
The use of the expandPath() method is of course entirely optional and in most cases is the same as simply specifying the exact system path to template.txt.
The FileTemplate type also accepts an optional encoding argument, in which you can pass the it the appropriate file type encoding it should use when reading the file that it will use as it's content source. If omitted, UTF-8 is assumed.
Initializing StringTemplate
Demarcating Template Variables
Each Template implementation does not care necessarily HOW you specify replacement markers in your template. The format is entirely up to you. For our sample template, we'll go with a very straight-forward set of content markers which will be preceeded with an underscore and written in all caps. There's a benefit to this type of variable demarcation which I'll get into in a moment - but again let me restate, format is entirely up to you! The content markers could just as easily be written in tag form such as <template:recipient />, it's your call.
The replace() function exposed by the Template interface returns the mutated string containing the content with the injected variables. This method expects a structure containing any number of key/value pairs - the keys must represent content markers and the values - well, represent the value with which that content marker must be replaced. Seeing as how we used very "key-friendly" content markers in our above template, replacement is simple;
The results variable now contains the following content;
Dear Mr. Werbenjagermanjensen, You owe me two dollars, I want my two dollars. Best Regards, Me
Advanced Template Usage
Of course you're probably thinking to yourself right now - "If I'm passing in an implicit structure into the replace() method, then how would I replace template variables that contained special characters, tags for instance". Enter the second more advanced template variables replacement technique.
Not only do templates support the replacement of variables that contain special characters, but you can also create more powerful template replacement rules by providing the replacement "key" as a regular expression. This is simply done by creating the replacement structure prior to invoking the replace() method, and using CF's associative array notation - where key's can contain any character you like.
In our next example, not only are we going to replace the content markers we've explicitly defined, we're going to leverage the advanced replacement facilities of CF and the templating API to arbitrarily swap out any instance of the letter "e" and "a" with "y" - to produce something obviously nonsensical;
The above replacement key contains a regular expression indicating that any occurrences of the letters "e" OR "a" should be replaced with the letter "y". Which produces;
Dyyr _RyCIPIyNT, _CONTyNT Byst Rygyrds, _SyNDyR
The original markers were never replaced in the previous code - so we simply get back the original template with, as expected, all instances of "e" and "a" replaced with "y". Content markers with special characters are also handled in the same form of structure notation;
Which would replace any occurrence of <template:replaceme /> within the template itself.