README

Path: README
Last Update: Sun Sep 19 19:29:08 CEST 2004

About

Tangerine is a general-purpose templating system written in Ruby.

It fits nicely to the object-oriented model and is, due effective code "compilation" faster than usual template systems, like for example ERB.

Tangerine is not specific to any output; you can create all kind of text. There are two special classes, however—Tangerine::XML and Tangerine::RFC822—which provide automatic (but overrideable) XML/RFC822 escaping. Additional escaping code for special formats can be added easily.

Tangerine does not have any requirements other than Ruby >= 1.8.

Usage

Tangerine uses a two-step approach to templating. First it will parse the template and generate code for it. This is done at instantiation. After generation, you can pass the template around and expand it on arbitrary objects. (Which should have the same interface if you want the template to work, of course.)

A typical usage would be something like:

  # Parse template:
  template = Tangerine.new File.read("my/template/file.tng")

  # Construct object:
  object.heading = "Tangerine Developers"
  object.members << Person.new("Christian", "Neukirchen", "chneukirchen@gmail.com")

  # Expand template into a file:
  File.open("my/output/file.html", "w") { |f| f.puts template.expand(object) }

Tangerine Templates

Tangerine uses a very easy to pick up templating language that is output-agnostic.

All text is passed verbatim, except so called tags. Tags are introduced using two commas (,,); various flags may follow. After these, you write the tag content. It is either

  • a ruby method name to be sent to the object, written as-is:
      ,,author
      ,,heading
      ,,recent?
    
  • an array-like accessor to be retrieved from the object, written as usual:
      ,,[1]
      ,,['hashkey']
    
  • or arbitrary code to get instance_evaled, enclosed in parentheses (which need to match):
      ,,(1+1)
      ,,(Time.now)
      ,,(author.upcase)
      ,,(self['key'].reverse)
    

Valid flags are (and must, if you want to use several of them, be in this order):

  • # (Hash): Comment; ignore everything until the end of this line.
  • | (Pipe): Indent the expansion to the current column.
  • ! (Bang): Don‘t apply any escaping code.
  • @ (At): Look up the tag in the tag library (see below).

After the tag content, there goes the optional tag block, enclosed in curly brackets that come directly after the tag name. This block is a sub-template following the same rules as any Tangerine template. It gets applied to each element if the tag content evaluates to an Enumerable, or only once with the return value if it is true. The braces need to match.

    ,,recent?{Recent entry}
    ,,authors{
      Name: ,,name
      Mail: ,,mail
    }

Tag libraries

Tag libraries provide an easy way to build and structure complex templates. Tags starting with @ are looked up using the tag library which is given as the second argument to Tangerine.new (any may be changed using the accessor Tangerine#taglib=).

Tag libraries are objects that implement resolve(tag) and return a string that gets evaluated as a Tangerine template instead of the tag upon calling that method.

One sample tag library that maps tags to files is included as Tangerine::FileLib.

Copyright and License

Copyright (C) 2004 Christian Neukirchen <purl.org/net/chneukirchen>

Tangerine is licensed under the same terms as Ruby itself.

Version

See Tangerine::VERSION.

[Validate]