ruby-tmpl: Code Examples

Set the template file

To set the file to use the Template#file method.
tmpl.file = "test.tmpl"

This file has to be readable by the executing UID.

Variable substitution

Script file: Set a variable in your template object by using the Template#set method.
tmpl.set('test', "ruby-tmpl test substitution")

To have the substitution work, you need to tell ruby-tmpl where to perform the substitution in the template file. To do so, you need to put something similar in your template file in the desired place.
<?tmpl.var name="test"?>

Object substitution

Script file: Set an object in your template object by using the Template#set_obj method. Use the following class as an example.

class MyTable < Array
  def to_html(style = nil)
    output = ''
    self.each do |x|
      output << "#{x}"
    end
    return(output)
  end
end
table = MyTable.new
table.push('my','list')
tmpl.set_obj('my table', table)

To have the substitution work, you need to tell ruby-tmpl where to perform the substitution in the template file. To do so, you need to put something similar to the following in your template file in the desired place.

<table border="1"><?tmpl.obj name="my table"?></table>

The above should result in a table. Note that the opening and closing table tags were manually specified. This was done intentionally that way the HTML designer can specify the column headers. This is a new feature that isn't complete and is only found in the CVS tree at the moment and is undergoing further development.

Munge Output

To have the output of ruby-tmpl not munged, set the Template#munge_output variable to false. By default, all output is munged (removes excess whitespace) so you only need to do this if you're using <pre> tags (or some whitespace preserving HTML), or are debugging.
tmpl.munge_output = false

Print the template

To print the output of the Template, use the Template#print method. This method will compile the template if it has not already been done so.
tmpl.print

Change the output to a file

Output from test.rbx

Print template for use elsewhere

To return the output of a template without using one of ruby-tmpl's builtin ways of outputting the document, you can return a dup'ed copy of the output via the to_s instance method. This allows for using ruby-tmpl to generate emails or other templatable material that is outside of the originally designed scope for ruby-tmpl.

Name spaces

Let's say I have a template, main.tmpl that defines a simple page layout. Let's also say that I have a second template, widget.tmpl that defines a widget, such as a bordered textbox with some roll-over behavior. widget.tmpl contains, amongst the HTML, something similar to:

<?tmpl.var name='widget.bgcolor' default='blue' ?>

Now let's suppose I want to have my main template page include several of these widgets:

<!-- some HTML -->
<?tmpl.file name='widget.tmpl' ?>
<?tmpl.file name='widget.tmpl' ?>
<?tmpl.file name='widget.tmpl' ?>
<!-- more HTML -->

The problem is that this inserts identical copies of the widget, with identical <?tmpl.var?> items. So I have no way of setting individual values. If I have this code:

tmpl.set('widget.bgcolor', "red")

*ALL* of the widgets on the page become red; I can't set one to blue, and another to yellow. I can only do this if every <?tmpl.var?> has a unique name attribute, which means three widget files and who would want to do that???

The solution is to use the <?tmpl.file?> and specify an additional attribute called 'ns' which is simply some prefix value. When <?tmpl.file?> gets called, and there is an 'ns' arg, then the file being included gets interpolated in a different namespace (a union of the new name space and the global namespace).

If there is no 'ns' arg, then <?tmpl.file?> just loads the included file and uses the standard (global) namespace for variable interpolation.

<?tmpl.file name='widget.tmpl' ns='top' ?>

will cause the contents of widget.tmpl to get interpolated by <?tmpl.file?> in the 'top' namespace, so that it converts

<?tmpl.var name='widget.bgcolor' default='blue' ?>

into

<?tmpl.var name='top:widget.bgcolor' default='blue' ?>

at runtime. Then, since the var now has a unique name in the uber-template, my code (index.rbx) can call

tmpl.set('top:widget.bgcolor', "red")

An email example

This is so easy, I'm just going to show you code. In your email template, use something similar to the following:

From: "New Accounts" <newaccounts@example.com>
To: "<?tmpl.var name="fname"?> <?tmpl.var name="lname"?>" <<?tmpl.var name="email"?>>
Subject: Welcome to Example.com!
 
<?tmpl.var name="fname"?>, welcome to Example.com!
 
Thank you for joining Example.com!
 
        -- Example.com Support <support@example.com>

And in your ruby script, use the following:

require 'ruby-tmpl'
require 'net/smtp'
 
tmpl = Template.new
tmpl.path = '/www/username/host.example.com/tmpl'
tmpl.file = 'email/signup-user.tmpl'
tmpl.set('fname', fname)
tmpl.set('lname', lname)
tmpl.set('email', email)
tmpl.set('username', username)
tmpl.use_mod_ruby = false
tmpl.munge_output = false
smtp = Net::SMTP.new('mailhost.internal')
smtp.start('mail.example.com')
smtp.ready('newaccounts@example.com', email) do |m|
m.write tmpl.to_s
end

Think you'll be able to live through that?