Before you can parse a template with Radius you need to create a Context object which defines the tags that will be used in the template. This is actually quite simple:
require 'radius' context = Radius::Context.new context.define_tag "hello" do |tag| "Hello #{tag.attr['name'] || 'World'}!" end
Once you have defined a context you can easily create a Parser:
parser = Radius::Parser.new(context) puts parser.parse('<p><radius:hello /></p>') puts parser.parse('<p><radius:hello name="John" /></p>')
This code will output:
<p>Hello World!</p> <p>Hello John!</p>
Note how you can pass attributes from the template to the context using the attributes hash. Above, the first tag that was parsed didn’t have a name attribute so the code in the hello tag definition uses “World” instead. The second time the tag is parsed the name attribute is set to “John” which is used to create the string “Hello John!”. Tags that do not follow this rule will be treated as if they were undefined (like normal methods).
Radius also allows you to define “container” tags. That is, tags that contain content and that may optionally manipulate it in some way. For example, if you have RedCloth installed you could define another tag to parse and create Textile output:
require 'redcloth' context.define_tag "textile" do |tag| contents = tag.expand RedCloth.new(contents).to_html end
(The code tag.expand above returns the contents of the template between the start and end tags.)
With the code above your parser can easily handle Textile:
parser.parse('<radius:textile>h1. Hello **World**!</radius:textile>')
This code will output:
<h1>Hello <b>World</b>!</h1>
But wait!–it gets better. Because container tags can manipulate the content they contain you can use them to iterate over collections:
context = Radius::Context.new context.define_tag "stooge" do |tag| content = '' ["Larry", "Moe", "Curly"].each do |name| tag.locals.name = name content << tag.expand end content end context.define_tag "stooge:name" do |tag| tag.locals.name end parser = Radius::Parser.new(context) template = <<-TEMPLATE <ul> <radius:stooge> <li><radius:name /></li> </radius:stooge> </ul> TEMPLATE puts parser.parse(template)
This code will output:
<ul> <li>Larry</li> <li>Moe</li> <li>Curly</li> </ul>
Note how the definition for the name tag is defined. Because “name” is prefixed with “stooge:” the name tag cannot appear outside the stooge tag. Had it been defined simply as “name” it would be valid anywhere, even outside the stooge tag (which was not what we wanted). Using the colon operator you can define tags with any amount of nesting.
During normal operation, you will often want to expose certain objects to your templates. Writing the tags to do this all by hand would be cumbersome of Radius did not provide several mechanisms to make this easier. The first is a way of exposing objects as tags on the context object. To expose an object simply call the define_tag method with the for option:
context.define_tag "count", :for => 1
This would expose the object 1 to the template as the count tag. It’s basically the equivalent of writing:
context.define_tag("count") { 1 }
So far this doesn’t save you a whole lot of typing, but suppose you want to expose certain methods that are on that object? You could do this:
context.define_tag "user", :for => user, :expose => [ :name, :age, :email ]
This will add a total of four tags to the context. One for the user variable, and one for each of the three methods listed in the expose clause. You could now get the user’s name inside your template like this:
<radius:user><radius:name /></radius:user>
If “John” was the value stored in user.name the template would render as “John”.
In the example above we made reference to user.name in our template by using the following code:
<radius:user><radius:name /></radius:user>
There is a much easer way to refer to the user.name variable. Use the colon operator to “scope” the reference to name:
<radius:user:name />
Radius allows you to use this shortcut for all tags.
By default, all Radius tags must begin with “radius”. You can change this by altering the tag_prefix attribute on a Parser. For example:
parser = Radius::Parser.new(context, :tag_prefix => 'r')
Now, when parsing templates with parser, Radius will require that every tag begin with “r” instead of “radius”.
Context#tag_missing behaves much like Object#method_missing only it allows you to define specific behavior for when a tag is not defined on a Context. For example:
class LazyContext < Radius::Context def tag_missing(tag, attr, &block) "<strong>ERROR: Undefined tag `#{tag}' with attributes #{attr.inspect}</strong>" end end parser = Radius::Parser.new(LazyContext.new, :tag_prefix => 'lazy') puts parser.parse('<lazy:weird value="true" />')
This will output:
<strong>ERROR: Undefined tag `weird' with attributes {"value"=>"true"}</strong>
Normally, when the Radius Parser encounters an undefined tag for a Context it raises an UndefinedTagError, but since we have defined #tag_missing on LazyContext the Parser now outputs a nicely formated error message when we parse a string that does not contain a valid tag.
Radius passes a TagBinding into the block of the Context#define_tag method. The tag binding is useful for a number of tasks. A tag binding has an #expand instance method which processes a tag’s contents and returns the result. It also has a #attr method which returns a hash of the attributes that were passed into the tag. TagBinding also contains the TagBinding#single? and TagBinding#double? methods which return true or false based on wether the tag is a container tag or not. More about the methods which are available on tag bindings can be found on the Radius::TagBinding documentation page.
A TagBinding also contains two OpenStruct-like objects which are useful when developing tags. TagBinding#globals is useful for storing variables which you would like to be accessible to all tags:
context.define_tag "inc" do |tag| tag.globals.count ||= 0 tag.globals.count += 1 "" end context.define_tag "count" do |tag| tag.globals.count || 0 end
TagBinding#locals mirrors the variables that are in TagBinding#globals, but allows child tags to redefine variables. This is valuable when defining context sensitive tags:
class Person attr_accessor :name, :friend def initialize(name) @name = name end end jack = Person.new('Jack') jill = Person.new('Jill') jack.friend = jill jill.friend = jack context = Radius::Context.new do |c| c.define_tag "jack" do |tag| tag.locals.person = jack tag.expand end c.define_tag "jill" do |tag| tag.locals.person = jill tag.expand end c.define_tag "name" do |tag| tag.locals.person.name rescue tag.missing! end c.define_tag "friend" do |tag| tag.locals.person = tag.locals.person.friend rescue tag.missing! tag.expand end end parser = Radius::Parser.new(context, :tag_prefix => 'r') parser.parse('<r:jack:name />') #=> "Jack" parser.parse('<r:jill:name />') #=> "Jill" parser.parse('<r:jill:friend:name />') #=> "Jack" parser.parse('<r:jack:friend:friend:name />') #=> "Jack" parser.parse('<r:jill><r:friend:name /> and <r:name /></r:jill>') #=> "Jack and Jill" parser.parse('<r:name />') # raises a Radius::UndefinedTagError exception
Notice how TagBinding#locals enables intelligent nesting. “<r:jill:name />” evaluates to “Jill”, but “<r:jill:friend:name />” evaluates to “Jack”. Locals lose scope as soon as the tag they were defined in closes. Globals on the other hand, never lose scope.
The final line in the example above demonstrates that calling “<r:name />” raises a TagMissing error. This is because of the way the name tag was defined:
tag.locals.person.name rescue tag.missing!
If person is not defined on locals it will return nil. Calling #name on nil would normally raise a NoMethodError exception, but because of the ‘rescue’ clause the TagBinding#missing! method is called which fires off Context#tag_missing. By default Context#tag_missing raises a UndefinedTagError exception. The ‘rescue tag.missing!’ idiom is extremly useful for adding simple error checking to context sensitive tags.
When Radius is presented with two tags that have the same name, but different nesting Radius uses an algorithm similar to the way winning rules are calculated in Cascading Style Sheets (CSS) to determine which definition should be used. Each time a tag is encountered in a template potential tags are assigned specificity values and the tag with the highest specificity wins.
For example, given the following tag definitions:
nesting extra:nesting parent:child:nesting
And template:
<r:parent:extra:child:nesting />
Radius will calculate specificity values like this:
nesting => 1.0.0.0 extra:nesting => 1.0.1.0 parent:child:nesting => 1.1.0.1
Meaning that parent:child:nesting will win. If a template contained:
<r:parent:child:extra:nesting />
The following specificity values would be assigned to each of the tag definitions:
nesting => 1.0.0.0 extra:nesting => 1.1.0.0 parent:child:nesting => 1.0.1.1
Meaning that extra:nesting would win because it is more “specific”.
Values are assigned by assigning points to each of the tags from right to left. Given a tag found in a template with nesting four levels deep, the maximum specificity a tag could be assigned would be:
1.1.1.1
One point for each of the levels.
In practice, you don’t need to understand this topic to be effective with Radius. For the most part you will find that Radius resolves tags precisely the way that you would expect. If you find this section confusing forget about it and refer back to it if you find that tags are resolving differently from the way that you expected.