A Text Template Class
By Anton Bawab
Those of us familiar with PERL appreciate the various modules it offers, and when it
comes to web design, I personally miss the various TEMPLATE modules available. So here
is my own version of the Text::Template module. (Note that there are
other articles on 4Guys (see
A Jscript Port of the Perl FastTemplate Module)
that provide similar functionality. A major difference, however, is that I present the
functionality in a VBScript class.)
Modules for PERL (as best as I can describe them) are like objects for ASP or VBScript.
The Text::Template module allows the programmer to create templates with
the variables embeded in them, and at run time merge the template with the actual value
of the variables resulting from the script. A typical example would be a mail merge
letter. I know a seasoned programmer would already have more uses in mind for such a
utility.
Well here it is, the TextTemplate class. The class provides functionality
similar to that of Text::Template to VBScript/ASP programmers. Its sources
can either be a string from within the running script or an external file, and it can
output the result either to a text file, simply return it to the script or output it
through a Response.Write call. In addition to that, it allows the programmer
to define the delimiters used in the template.
Here's a small example, which is viewable as well through our on-line demo. Start with a typical template:
{date()}
Dear {name};
Your current outstanding balance is at {FormatCurrency(current_balance,2)}.
Be so kind to settle your account within {time_period}.
Sincerely,
{login_name}
|
The following script would load the letter, go through it and replace the contents of the curly braces (the variables that is) with the actual values they hold from the script.
|
Notice that placeholders defined in the template must have corresponding variable
names in the script that uses the template. Also, the virtual or physical path to the correct
template must be known, since the Source property. If all you know is the
virtual path, use the Server.MapPath method to translate the virtual path
into the physical path. (For more information on Server.MapPath, be sure
to read: Using Server.MapPath.)
Also note that the Replace function was used to convert the vbCrLfs
into <BR>s. This is needed since HTML ignores carraige returns and
whitespace. Without this Replace statement, the output would appear in one
long string. (Read the technical
docs on the Replace function.)
Now the output of that script would look like this:
09/04/2000 Dear Joe Blow; Your current outstanding balance is at $15,000.00 Be so kind to settle your account within 2 weeks. Sincerely, Anton Bawab |
Notice how the date value was replaced as well, even if it was not explicitly set in
the script. The class uses the eval() statement to replace the contents of
the curly braces (or whatever other delimiters you use) with their value from the same
namespace of the running script, that includes calls for other VBScript functions like
the FormatCurrency() or Date(). The eval()
statement fails however when the value it is replacing contains quotation marks. In
replacing values from a recordset, I had to use the objRS(0) rather than
the objRS("Client_Name") in the template. Here objRS is my
RecordSet object.
Here is a list of the properties the class takes and a small description of what they are :
| Property | Description |
|---|---|
SourceType
|
String - Required Accepts one of two values : FILE, STRING FILE => the template is in a text file STRING => the template is in a STRING variable in the running script This property HAS to be set BEFORE the Source property |
Source
|
String - Required Sets the name of the template. In the case of a file template, give the absolute path or if used in an ASP context use the MapPath() method of the Server object.
|
Delimiter
|
String - Optional - Default {}Sets the opening and the closing delimiters used to hold the variables in the template. This property accepts a two character string, splits it in two and uses the first as the opening delimiter, and the second as the closing delimiter. The opening and the closing delimiters can be the same. The property will not accept parenthesis nor square brackets. |
| Method | Description |
|---|---|
fill_in
| Returns the template with the values of the variables already replaced. |
fill_in_ASP
| Writes the template with the values of the variables already replaced to the Response object in an ASP context. |
fill_in_file(filespec)
| Writes teh template with the values of the variables already replaced to a text file where filespec is the path of that file. This will not work in an ASP context if the user does not have sufficient rights to the folder you are attempting to write to. NOTICE: This method will overwrite files with the same name in the target destination. This is by design. |
If you miss one of the properties or the class has a problem resolving one of them, an error message is returned instead of the intended string. In case of writing to a file, the error message is actually written to the file.
If you need to use the fill_in method repetitively (like when you iterate
through a the records of a recordset) there is no need to define your source and source
type everytime your values change. All you have to do is call one of the fill_in
methods and it will use the same template text.
I originally wrote this class to avoid hard coding long strings with line breaks and tabs in my scripts. The first need was when I had to send e-mail messages using ADO and JMail. Now I have could separate the data retrieval and the actual mailing from the body text of the message (which anybody can write now !!). Now that I see it in action, I already have some ideas about how I can separate the content from the scripting in our intranet.
Happy Programming!
Attachments:
TextTemplate class
