Permalink
Browse files

updated documentation

  • Loading branch information...
1 parent dd2a7e0 commit 1db6f9b4b78214b0c64cb6ccbf10053d2682a451 @jlong committed Jan 23, 2006
Showing with 71 additions and 23 deletions.
  1. +55 −17 radius/QUICKSTART
  2. +3 −1 radius/README
  3. +1 −1 radius/ROADMAP
  4. +1 −1 radius/Rakefile
  5. +11 −3 radius/lib/radius.rb
View
72 radius/QUICKSTART
@@ -1,4 +1,6 @@
-=Quick Start
+= 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 pretty simple:
@@ -17,16 +19,19 @@ Once you have defined a context you can create a Parser and parse to your heart'
puts parser.parse('<p><radius:hello /></p>')
puts parser.parse('<p><radius:hello name="John" /></p>')
-This will output:
+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
-(which is passed in as the first parameter.). Above the first tag that was parsed didn't have
+(which is passed in as the first parameter). Above, the first tag that was parsed didn't have
a name attribute so the code in the +hello+ method 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!".
+John!". <b>All tag definitions must accept only one parameter--the attributes hash.</b> 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
@@ -45,17 +50,14 @@ With the code above your parser can easily handle Textile:
parser.parse('<radius:textile>h1. Hello **World**!</radius:textile>')
-This will output:
+This code will output:
<h1>Hello <strong>World</strong>!</h1>
-But wait!--it gets better. Because container tags can manipulate what they contain you can use
-them to iterate over collections:
+But wait!--it gets better. Because container tags can manipulate the content they contain
+you can use them to iterate over collections:
class ThreeStoogesContext < Radius::Context
- def initialize
- @prefix = 'ts'
- end
def stooge(attr)
content = ''
["Larry", "Moe", "Curly"].each do |name|
@@ -73,15 +75,15 @@ them to iterate over collections:
template = <<-TEMPLATE
<ul>
- <ts:stooge>
- <li><ts:name /></li>
- </ts:stooge>
+ <radius:stooge>
+ <li><radius:name /></li>
+ </radius:stooge>
</ul>
TEMPLATE
puts parser.parse(template)
-This will output:
+This code will output:
<ul>
@@ -93,6 +95,42 @@ This will output:
</ul>
-The above code also illustrates how you can set the prefix instance variable to control the
-string that prefixes Radius tags. By setting the prefix to "ts" our tags must begin with "ts"
-instead of "radius" like they did in the other examples.
+
+== Altering the Tag Prefix
+
+By default, all Radius tags must begin with "radius". You can change this by altering the
+prefix attribute on a Context. For example:
+
+ class MyContext < Radius::Context
+ def initialize
+ @prefix = 'r'
+ end
+ end
+
+Now, when parsing templates with MyContext, Radius will require that tags begin with "r".
+
+
+== Using Context#tag_missing to Define Behavior for Missing 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 initialize
+ @prefix = 'lazy'
+ end
+ def tag_missing(tag, attr, &block)
+ "<strong>ERROR: Undefined tag `#{tag}' with attributes #{attr.inspect}</strong>"
+ end
+ end
+
+ parser = Parser.new(LazyContext.new)
+ puts parser.parse('<lazy:weird value="true" />')
+
+This code 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 our custom message.
View
4 radius/README
@@ -46,4 +46,6 @@ Contact me and we'll talk. :)
Enjoy!
--- John Long :: http://wiseheartdesign.com
+--
+John Long ::
+http://wiseheartdesign.com
View
2 radius/ROADMAP
@@ -13,6 +13,6 @@ This is a prioritized roadmap for future releases:
http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/127640/
Update: See link:files/DSL-SPEC.html for a fuller explanation of how
- the DSL should behave.
+ the DSL might behave.
4. Optimize for speed. Incorporate strscan?
View
2 radius/Rakefile
@@ -14,7 +14,7 @@ RDOC_EXTRAS = ["README", "QUICKSTART", "ROADMAP", "DSL-SPEC", "CHANGELOG"]
Rake::RDocTask.new do |rd|
rd.title = 'Radius -- Powerful Tag-Based Templates'
- rd.main = "README"
+ rd.main = "Radius"
rd.rdoc_files.include("lib/**/*.rb")
rd.rdoc_files.include(RDOC_EXTRAS)
rd.rdoc_dir = 'doc'
View
14 radius/lib/radius.rb
@@ -1,14 +1,20 @@
module Radius
- class ParseError < StandardError # :nodoc:
+ # Abstract base class for all parsing errors.
+ class ParseError < StandardError
end
- class MissingEndTagError < ParseError # :nodoc:
+ # Occurs when Parser cannot find an end tag for a given tag in a template or when
+ # tags are miss-matched in a template.
+ class MissingEndTagError < ParseError
+ # Create a new MissingEndTagError object for +tag_name+.
def initialize(tag_name)
super("end tag not found for start tag `#{tag_name}'")
end
end
+ # Occurs when Context#render_tag cannot find the specified tag on a Context.
class UndefinedTagError < ParseError
+ # Create a new MissingEndTagError object for +tag_name+.
def initialize(tag_name)
super("undefined tag `#{tag_name}'")
end
@@ -40,6 +46,8 @@ def render_tag(tag, attributes = {}, &block)
end
# Like method_missing for objects, but fired when a tag is undefined.
+ # Override in your own Context to change what happens when a tag is
+ # undefined. By default this method raises an UndefinedTagError.
def tag_missing(tag, attributes, &block)
raise UndefinedTagError.new(tag)
end
@@ -76,7 +84,7 @@ class Parser
# The Context object used to expand template tags.
attr_accessor :context
- # Creates a new parser object initialized with a context.
+ # Creates a new parser object initialized with a Context.
def initialize(context = Context.new)
@context = context
end

0 comments on commit 1db6f9b

Please sign in to comment.