jlong/radius

= Radius Quick Start


== Defining Tags

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).


== Container Tags

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 <tt>tag.expand</tt> 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>


== Nested Tags

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.


== Exposing Objects to Templates

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 <tt>1</tt> 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 <tt>user</tt> 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 <tt>user.name</tt> the template would render as "John".


== Tag Shorthand

In the example above we made reference to <tt>user.name</tt> in our template by using the
following code:

  <radius:user><radius:name /></radius:user>
  
There is a much easer way to refer to the <tt>user.name</tt> variable. Use the colon operator
to "scope" the reference to <tt>name</tt>:

  <radius:user:name />

Radius allows you to use this shortcut for all tags.
  

== Changing the Tag Prefix

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


== Custom Behavior for Undefined Tags

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.


== Tag Bindings

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.


== Tag Binding Locals, Globals, and Context Sensitive Tags

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.


== Tag Specificity

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.