Using Template Spec

What is Template Spec ?

Amrita2 is an HTML-Ruby compiler and needs additional information to compile a HTML template to Ruby modules. That is what we call Template Spec .

Why and When

If Template Spec was not given, TO will generate a default Spec and use it for compiling. If the default was not enough, you can give a manually made Spec to TO.

And I'm planing to solve performance problems by using Specs later.

How to use Template Spec

sample source

--- ../sample/spec/spec.rb ---
require "amrita2/template"
include Amrita2

class PO
  def title
    "hello world"
  end

  def body
    "Amrita2 is a html template libraly for Ruby"
  end
end

TEMPLATE_TEXT = <<END
<html>
   <body>
      <h1 id='title'>title will be inserted here</h1>
      <p>body text will be inserted here</p>
   </body>
</html>
END


tmpl = TemplateText.new(TEMPLATE_TEXT) do
  Amrita2::define_template_spec do 
    dynamic_element(:title)
    dynamic_element(:body, :matcher=>HtmlTag::P)
  end
end
tmpl.expand(STDOUT, PO.new)

output
<html>
   <body>
      <h1 id='title'>hello world</h1>
      <p>Amrita2 is a html template libraly for Ruby</p>
   </body>
</html>

description

tmpl = TemplateText.new(TEMPLATE_TEXT) do
  Amrita2::define_template_spec do 
    dynamic_element(:title)
    dynamic_element(:body, :matcher=>HtmlTag::P)
  end
end

The block given to TemplateText.new is a Template Spec.

The top level must be 'Amrita2::define_template_spec' and consists of some 'dynamic_element's .

'dynamic_element's must have a Symbol as id and optionaly a Hash as options.

:matcher is an options for using an HTML element without id for dynamic element. In this case, an element with TAG <p> will be used as dynamic element named :body.

amrita:type and Template Spec

amrita:type is a set of Spec options and supposed to be a shortcut for Template Spec.

amrita:id's are defined in template.rb like this.

DefaultTypeMap = { 
  # amrita:id name => { Spec options ... }
  :use_args => { :use_args => true},
  :use_original_element=> { :use_original_element => true},
  :expand_by_member => { :expand_by_member => true },
  :value_attr => { :value_attr => true },
  :erb => { :erb => true },
  :link => { :link_attr => [:href, [/javascript:.*/]] },
  :input => { :value_attr => :value },
  :checkbox => { :value_attr => :checked },
  :select => { :selection_element => [:selected, []] },
}

Template Spec options

key_attr_name
attribute name for binding. Default is :id
matcher
matcher object for matching Template Element and dynamic element
delete_tag
If :idtrue, the tag will be deleted in the output
output_stream
If specified, the output for this element will be inserted into the position of specified elements
delete_id
If :idtruetrue, the attribute :idtruetrue:key_attr_name will be deleted
place_holder
(not documented)
direct_define
(not documented)
match_many
(not documented)
generate_template
(not documented)
encoding
(not documented)
dummy_element
(not documented)
parts_element
(not documented)
ie_hack
(not documented)
check_true
(not documented)
use_original_element
(not documented)
expand_by_member
(not documented)
use_args
(not documented)
value_attr
(not documented)
link_attr
(not documented)
selection_element
(not documented)
erb
(not documented)
use_single_arg
(not documented)
use_erb_args
(not documented)

samples

Using Amrita2 with Template without id attributes

--- ../sample/spec/matcher.rb ---
require "amrita2/template"
include Amrita2
include Amrita2::Core

class PO
  def title
    "hello world"
  end

  def body
    "Amrita2 is a html template libraly for Ruby"
  end

  def ulist
    { 
      :item1=>1,
      :item2=>2,
      :item3=>3
    }
  end
end

# Amrita2 can use template without id attributes
TEMPLATE_TEXT = <<END
<html>
   <body>
      <h1 class='title'>title will be inserted here</h1>
      <p>body text will be inserted here</p>
      <ul>
        <li></li>
        <li></li>
        <li>line3</li>
      </ul>
   </body>
</html>
END

# user defined matcher
class TextMatcher < Matcher
  def initialize(text)
    @text = text
  end

  def match(e)
    e.text == @text
  end
end

tmpl = TemplateText.new(TEMPLATE_TEXT) do
  Amrita2::define_template_spec do 
    # match with element with attribute class='title'
    dynamic_element(:title, :matcher=>AttrMatcher.new(:class, 'title'))
    # match with tag <p>
    dynamic_element(:body, :matcher=>HtmlTag::P)
    # match with tag <ul>
    dynamic_element(:ulist, :matcher=>TagMatcher.new(:ul)) do 
      # match with tag <li>
      dynamic_element(:item1, :matcher=>HtmlTag::LI)
      # match any element 
      dynamic_element(:item2, :matcher=>AnyMatcher.new)
      # match with element with text 'line3'
      dynamic_element(:item3, :matcher=>TextMatcher.new('line3'))
    end
  end
end
tmpl.expand(STDOUT, PO.new)

output
<html>
   <body>
      <h1 class='title'>hello world</h1>
      <p>Amrita2 is a html template libraly for Ruby</p>
      <ul>
        <li>1</li>
        <li>2</li>
        <li>3</li>
      </ul>
   </body>
</html>

Using Expand by Member feature

--- ../sample/spec/member.rb ---
require "amrita2/template"
include Amrita2


TEMPLATE_TEXT = <<END
<html>
<body>
<table id='flist'>
  <tr>
    <th>name</th>
    <th>size</th>
    <th>ctime</th>
    <th>mtime</th>
  </tr>
  <tr id='item'>
    <td id='name' />
    <td align='right' id='size' />
    <td id='ctime' />
    <td id='mtime' />
  </tr>
</table>
</body>
</html>
END

# add an attr to standard class File::Stat 
class File
  class Stat
    attr_accessor :name
  end
end


class PO
  def flist(m)
    m.flist do |mf| 
      Dir['*'].each do |f|
        stat = File::stat(f)
        stat.name = f
        mf.item(stat)
      end
    end
  end
end

tmpl = TemplateText.new(TEMPLATE_TEXT) do
  Amrita2::define_template_spec do 
    dynamic_element(:flist) do
      dynamic_element(:item, :expand_by_member=>true) do 
        dynamic_element(:name)
        dynamic_element(:size)
        dynamic_element(:ctime)
        dynamic_element(:mtime)
      end
    end
  end
end

tmpl.expand(STDOUT, PO.new)
output


   name     size            ctime                        mtime
spec.rb      519 Wed Mar 02 17:04:31 JST 2005 Wed Mar 02 16:18:42 JST 2005
matcher.rb  1395 Wed Mar 02 17:04:31 JST 2005 Wed Mar 02 16:38:15 JST 2005
attr.rb     1890 Wed Mar 02 17:04:31 JST 2005 Wed Mar 02 17:02:55 JST 2005
member.rb   1804 Wed Mar 02 17:28:24 JST 2005 Wed Mar 02 17:28:24 JST 2005

validating template with Template Spec

debuging PO without template

Using Tables

Using <dl>