SourceForge Logo

ruby-tmpl: Code Examples

Code Examples - Download - FAQ - Home - Lists - Reference - Summary - ViewCVS

Code Chunket Contents

Create a Template Instance

To create a Template instance in a mod_ruby script:

  1. Load the ruby-tmpl module into your local script: require "ruby-tmpl"
  2. Create the object: tmpl =
^^ Top ^^

Set the template search path

To add a template search path to your use the Template#path method. You can use either a string or an array.
tmpl.path = "/www/data/"
tmpl.path = ['./data', './tmpl']
tmpl.path = '/www/data/'

Make sure this directory is readable by the UID of whoever is running this script (UID of the webserver is often www or nobody). NOTES: This method takes an array of paths to search. If you want to specify multiple paths with a string, however, delimit the directories to search with a ':' character.

^^ Top ^^

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.

^^ Top ^^

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"?>

^^ Top ^^

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}"
table =
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.

^^ Top ^^

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

^^ Top ^^

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.

^^ Top ^^

Change the output to a file

To change the output of a template instance from STDOUT to a file, use the Template#out_file method. This method needs to be used before tmpl.print. For an example of a practical use of this, see the html.rbx script that is used to generate the ruby-tmpl www documentation
tmpl.out_file = 'foo.html'

^^ Top ^^

Output from test.rbx

To see an example of what test.rbx would look like on your server, you can look at test-rbx.html. Please note that this output is not dynamic and is created a head of time on a test machine and slightly modified for anonymity.

^^ Top ^^

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.

^^ Top ^^

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' ?>


<?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")

and refer to a single file, but give it three different values. Neat, huh? If you have further questions not answered by this, please send them to the ruby-tmpl-users mailing list.

^^ Top ^^

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" <>
To: "<?tmpl.var name="fname"?> <?tmpl.var name="lname"?>" <<?tmpl.var name="email"?>>
Subject: Welcome to!
<?tmpl.var name="fname"?>, welcome to!
Thank you for joining!
        -- Support <>

And in your ruby script, use the following:

require 'ruby-tmpl'
require 'net/smtp'
tmpl =
tmpl.path = '/www/username/'
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 ='mailhost.internal')
smtp.ready('', email) do |m|
m.write tmpl.to_s

Think you'll be able to live through that?

^^ Top ^^
$Id: examples.tmpl,v 1.6 2002/04/22 22:37:16 thetitan Exp $