r object)?ruby-tmpl is a templating system designed to work with or without mod_ruby, an Apache web server module. ruby-tmpl provides web developers with an abstraction layer that separates presentation (templates) and content (data or ruby scripts). Being able to develop large sites with a templated interface while still using the Ruby programming language is a Good Thing™.
Unlike AxKit which is XML/XSL oriented and very powerful (AxKit gets my full endorsement, is awesome, and well worth a hard look for large content driven sites!), sometimes it is too much for the problem at hand. Try this on for size: if static HTML is a $0.99 squirt gun from 7-eleven that barely gets your friend wet and AxKit is a tidal wave similar to the one shown in the deleted scenes of the movie the Abyss, then ruby-tmpl is a fire hose. It's big enough to keep a building from burning down, small enough to not wipe out the state of Florida, yet still capable of doing plenty of work/damage.
^^ Top ^^ruby-tmpl has three main components, but only two that you'll ever need to worry about. The first is the actual ruby-tmpl library (what the ruby-tmpl developers slave over and work on). The second component to ruby-tmpl are the template files and third is the actual mod_ruby script. The template and script files are the only things you'll have to work with and develop: ruby-tmpl is maintained by the developers and your only concern with it is to make sure that you stay current with stable versions (subscribe to ruby-tmpl-announce).
To use ruby-tmpl, you need to create at least two files: a template file and a script (though multiple scripts can call the same template file).
Template files control the presentation of your content. A template file has place holders for content. What the content is varies and this is where the power of ruby-tmpl comes from. As of this writing, there are only two types of data that can be put into a ruby-tmpl template: variables (<?tmpl.var ?>) and files (<?tmpl.file ?>). All templates are recursive by such that if you use a <tmpl.file/> tag in a template and that tag calls another template, which calls another template, then ruby-tmpl will perform the appropriate substitutions in order (NOTE: It is currently possible to create a template file that is recursive and loops forever! This is something that the development team is aware of and aiming to fix in the next release or two.). A <?tmpl.var ?> tag can call a <?tmpl.file ?> tag, and visa-versa.
The second file type is the actual mod_ruby script. This script/file has a very distinct and singular purpose: populate a template file with content. What content gets put into a template is dependent on the request's environment, parameters passed from a user, information stored in a persistence layer (Postgres, cdb, or MySQL database), etc. A script controls what content a template file(s) presents. A template file should control how the information is presented. All formatting decisions should be made in templates. These are very important concepts that are core to successfully using ruby-tmpl.
The following explanation assumes you have a valid script and template (see code examples and the doc/ dir for examples). When a request comes in for a ruby-tmpl script, Apache will hand the request off to mod_ruby, which will in turn load the script (ex: test.rbx). The script then loads the ruby-tmpl module and creates an instance of the Template class which is populated with data. The data that is loaded into the Template instance should be presented through the template file (ex: test.tmpl). After all of the content has been loaded into the script's Template object, the object "compiles" or "packs" the page and performs all of the substitutions, file tracing, recursion, etc. and stores a completed page ready to be printed out to the client. After a page has been compiled, output processing is performed on the data before being sent to the client through mod_ruby/Apache.
^^ Top ^^Here is a list of current features in ruby-tmpl (see FEATURES for the most up to date information):
Here is a list of desired/planned features in ruby-tmpl (see TODO file for the most up to date information):
Please feel free to send feature requests, comments, and even bugs and to the ruby-tmpl-devel list.
^^ Top ^^There are a few places to see examples of ruby-tmpl code:
Right here at http://ruby-tmp.sourceforge.net/test-rbx.html. Please note that the page has been altered slightly to preserve the anonymity of the server that ran the test as well as add basic navigation so that you can get back to the rest of the site. Other than that, yes, this page is 100% legit and from a real test.rbx script.
^^ Top ^^Check out the lists page. Descriptions of all of the lists as well as instructions on how to subscribe are located there.
^^ Top ^^Plenty and I know that the "tags" in ruby-tmpl are actually PIs. At the risk of sounding like an XML idiot, I'm inclined to include an explanation as to why I've chosen not to call template tags PIs (and it's a simple answer). Tags are nice and generic terms that everyone who uses HTML is familiar with. My goal isn't to appeal to the die-hard XML and doc dweebs of the world and instead is to get this piece of software out in mass use. To the XML fans in the crowd, I'm really sorry I botched the term tag and am using PI sloppily: it's marketing 101 and after years of living in Seattle, some of Microsoft's genius wore off on me. <:~) I suck, what can I say. If it helps you sleep any better, a PI is actually type of XML tag.
^^ Top ^^r object)?r is available, but has been encapsulated in ruby-tmpl and is aliased to tmpl.r. By and large it is a bad idea to use the Apache request object directly unless you know that your script won't be used in an offline context.
tmpl.docroot_include is one of the more powerful features in ruby-tmpl, but it's also a little hard to grasp at first. Imagine if you will the following directory structure:
| Directory | Purpose |
/ | Home |
/programming | Directory for programming |
/programming/ruby | Programming directory dedicated to the wonderful language of ruby |
Now lets say that you want to include some breadcrumbs along the top of the page that expand as you traverse deeper into the directory structure. One way to do this is to hard code the bread crumbs into each page, but that's no fun, especially if you want to change the breadcrumbs. A better way would be to use <?tmpl.docroot_include ?>. In each of your templates, you'd specify a tag similar to:
<?tmpl.docroot_include name=".breadcrumb.tmpl" spacer=" - " ?>
In each of the directories, create a file called .breadcrumb.tmpl. Each of the breadcrumb files would then include some basic HTML that would be directory specific (typically a link or just the name of the dir):
| File | HTML in file |
| /.breadcrumb.tmpl | <a href="/">Home</a> |
| /programming/.breadcrumb.tmpl | <a href="/programming/">Programming</a> |
| /programming/ruby/.breadcrumb.tmpl | <a href="/programming/ruby/">Ruby</a> |
And, after all of that, you'll get a nifty spiffy auto-generated breadcrumb navigation line that looks similar to (note: links are broken for the sake of consistency):
Home - Programming - Ruby
Cool, huh? This tag is designed to be used for navigation or page meta data such as the page title, or left nav bar, and obviously, bread crumbs.
^^ Top ^^This is cake. Use the to_s instance method. Check out the code example for implimentation reference.
^^ Top ^^