Using pagetemplate within Ruby applications.
Getting Started
Before you dig into the code, you might want to take a look at pagetemplate-the-designers-perspective
Using PageTemplate In Your Ruby Code
This is a very quick overview, because I just spent hours going over the designer documents and I’m a little tired.
First, of course, you’ll want to install the PageTemplate package. Once that’s done, require
the package.
You’ll need a PageTemplate object to hold values and parse template files.
At some point, you will want the PageTemplate object to load a template text file, bristling with directives. The template file should be readable by the script, and the path must be either absolute or relative to the script’s working directory.
To assign a value for use by PageTemplate, use hash-style assignment, with the name to be used by the template as the key, and the value assigned as — well — the value. The only rule is that the value must evaluate to a String. Either it is a String or it has a to_s
method). Page designers would probably be grateful if the key was a string, too. Much easier to type it into a text template that way.
The easiest way to handle flags used in if
directives is to take advantage of Ruby’s boolean values.
You can use the truth of a regular variable or loop variable in an if
directive, but remember that Ruby is more specific about false
than other languages you might be used to. For example, the number zero is not false. It’s just zero. Same with empty strings. If you want a variable to be interpreted as false
, you should explicitly set it.
PageTemplate uses arrays of objects for lists. Each object provides a local namespace which lasts only for the current iteration through the chunk of content. Otherwise, you’d have to manually set loop variables, and I don’t like that idea!
The classic approach is to borrow from HTML::Template and use a list of hashes for your namespaces.
What about nested lists? They are handled the same way. One of the keys in your item hash points to another array of hashes, which will be used for the inner loop.
Using objects in a list requires a little more research, but it’s still a practical solution. Say you’re trying to figure out how to use PageTemplate in an image gallery. You might have an Image class with accessors that look something like this:
You can build your template armed with this knowledge.
Then, rather than waste precious minutes altering class Image
to respond to hash-based access, you can assign a list of Image
objects to the template list.
This approach definitely encourages maintaining a consistent interface. I wouldn’t want to go altering my template files (or telling the designer to alter her files) every time I get a bright idea for how Image
should work.
You can also refer to public methods of the object in your template, but that’s still a bit shaky. The methods have to accept calls with no arguments or blocks (Ex: image.thumbnail()
would be referenced as [%var thumbnail%]
).
Once you’ve told your PageTemplate object which file to load and what values to remember, you’ll probably want to display the neat custom page.
Of course, if you do things this way you’ll have to remember all of the HTTP header information. Life will be much easier for you if you just use the functionality provided by the standard CGI module for ruby.
I’m not a Rails person, so I really don’t know how well PageTemplate works with Rails these days. Definitely send reports if you have any troubles, though. See pagetemplate for links to bug filing and the forum.
Caching Templates
PageTemplate has some support for saving template information to disk. This means that your application needs less time to prepare its templates. You still need to provide a Namespace when you need output, though.
Two steps are required to take advantage of PageTemplate’s cache capabilities. First, make sure that your script has write permissions to the directory or directories that contain your template source. Next, call the PageTemplate constructor with the use_cache
flag set to true
.
Creating Your Own Syntax
For now, use the source as your guides.
Backlinks
Added to vault 2024-01-15. Updated on 2024-02-01