Company Logo Simplest html/xhtml template library for Ruby
Location:
Amrita Homepage > Documentation > Amrita tour
To Japanese

Amrita tour

modify attributes of HTML element

code and output

code:

require "amrita/template"
include Amrita

tmpl = TemplateText.new <<END
<table border="1">
  <tr><th>name</th><th>author</th><th>webpage</tr>
  <tr id=table1>
    <td id="name"></td>
    <td id="author"></td>
    <td><a id="webpage"></a></td>
  </tr>
</table>
END

data = {
  :table1=>[ 
    { 
      :name=>"Ruby", 
      :author=>"matz" , 
      :webpage=> a(:href=>"http://www.ruby-lang.org/") { "Ruby Home Page" },
    },
    { 
      :name=>"perl", 
      :author=>"Larry Wall" ,
      :webpage=> a(:href=>"http://www.perl.com/") { "Perl.com" },
    },
    { 
      :name=>"python", 
      :author=>"Guido van Rossum" ,
      :webpage=> a(:href=>"http://www.python.org/") { "Python Language Website" },
    },
  ] 
}
tmpl.prettyprint = true
#tmpl.use_compiler = true
tmpl.expand(STDOUT, data)

output:

<table border="1">
  <tr>
  <th>name</th>
  <th>author</th>
  <th>webpage</th>
  </tr>
  <tr>
  <td>Ruby</td>
  <td>matz</td>
  <td><a href="http://www.ruby-lang.org/">Ruby Home Page</a></td>
  </tr>
  <tr>
  <td>perl</td>
  <td>Larry Wall</td>
  <td><a href="http://www.perl.com/">Perl.com</a></td>
  </tr>
  <tr>
  <td>python</td>
  <td>Guido van Rossum</td>
  <td><a href="http://www.python.org/">Python Language Website</a></td>
  </tr>
</table>

description

The Amrita#a() method produce a Amrita::AttrArray object.

a(:href=>"http://www.ruby-lang.org/") { "Ruby Home Page" },

When this special object is used for a model data, it modifies HTML element's attributes and set text. So if template for this data is ...

<td><a id="webpage"></a></td>

The output will be....

<td><a href="http://www.ruby-lang.org/">Ruby Home Page</a></td>     

filelist.rb described in docs/XML uses AttrArray object too.

There is another way to do this, see expand attribute expand in docs/Tour2

proc

You can give a proc as model data to edit element manualy.

code and output

code:

require "amrita/template"
include Amrita

tmpl = TemplateText.new <<END
<ul>
  <li id=list><font id=data></font>
</ul>
END

languages = %w(java Ruby perl python c++ c sml cobol fortran ada lisp)
i = 0 
data = {
  :list => languages.collect do |l|
    {
      :data => proc do |elem|
        if l == "Ruby" # Ruby is special language to me!
          # use Amrita::Element's methods to edit
          elem[:color] = "red" 
          elem[:size] = "big"
          elem.set_text("I love Ruby!")
          # e() is Amrita's method that generates Element
          e(:em) { elem } 
        else
          i = i + 1 # i is shared by all procs
          elem[:color] = i%2 == 0 ? "blue" : "black"
          elem.set_text(l)
          elem
        end
      end
    }
  end
}
tmpl.prettyprint = true
tmpl.expand(STDOUT, data)

output:

<ul> 
  <li><font color="black">java</font> </li>
  <li><em><font color="red" size="big">I love Ruby!</font></em> </li>
  <li><font color="blue">perl</font> </li>
  ...
</ul>

description

If model data is a Proc object, Amrita calls it with Amrita::Element object that represents the HTML element.Amrita will replace the element by result of proc.

In that proc, you can edit Element freely.

setting an attribute

elem[:color] = "red" 

setting the text of element

elem.set_text("I love Ruby!")

generate a new Element with Amrita#e method

e(:em) { elem } 

In this case elem is <font color...>I love Ruby!</font>. The output is wrapped by \<em>....\</em> by e(:em) { .... }.

use custom classes for model data

code and output

code:

require "amrita/template"
include Amrita

tmpl = TemplateText.new <<END
<span id="time">
  <span id="year"></span>/<span id="month"></span>/<span id="day"></span>
</span>
END

t = Time.now
t.extend Amrita::ExpandByMember

data = { :time=>t }
tmpl.compact_space = true
tmpl.expand(STDOUT, data)

output:

2002/7/17

description

If the model data is kind_of Amrita::ExpandByMember, amrita uses id value as a method and call method of that name.

In this example, the data for :time is a Ruby's standard Time object but it extend ExpandByMember. So id's value year is treated as a method name and amrita calls that method of t.

So output for tempalte <span id="year"></span> get result of method call t.yera: "2002" . Thus the produces the output...

<span><span>2002</span>/<span>7</span>/<span>17</span></span>

Amrita deletes <span> element if there is no attributes after deleteing id attribute.So last output is

2002/7/17

precompile

Amrita can compile HTML template to Ruby code before expand.

code and output

code(the added code to table.rb) :

tmpl = TemplateText.new(TEMPLATE)
tmpl.use_compiler = true
tmpl.set_hint_by_sample_data(data) # optional: optimization to that data
tmpl.expand(STDOUT, data)  # with compiled code
puts "----code generated by Amrita -----------"
puts tmpl.src
puts "----code generated by Amrita end -------"

The output is same as table.rb with the benchmark report added. Here's my data on a Crusoe TM5600.

43.068354 seconds for 1000 times without compiling
5.078764 seconds for 1000 times with pre-compiled code

description

You only add one line for compiling

tmpl.use_compiler = true

After this, expand method will be executed by compiled code that produce (almost) same output.

And optionally give a sample data to amrita.

tmpl.set_hint_by_sample_data(data)

Amrita::HTMLCompiler uses this sample data for optimizing the output code. So, if data structure changes after it, you must call set_hint_by_sample_data again.

Amrita::HTMLCompiler can produce a code that include interpreter mode partially. If you need to compile and some part of model may change dynamically, you can give nil for data that may change.

Amrita::Compiler call Element::expand method in compiled code at that point.

You can take trade off of speed and flexibility at any point you like.

Sanitizing - anti XSS attack

Amrita has a built in Amrita::Sanitizer to protect against XSS(cross site scripting) attacks. Amrita::Formatter uses this module automaticaly.

code and output

require "amrita/template"
include Amrita

tmpl = TemplateText.new %q[<p id=body>xxx</p>]
data = {
 :body=>"I want to insert new line.<br>But I can't"
}
tmpl.expand(STDOUT, data) # <p>I want to insert new line.&lt;br&gt;But I can't</p>
puts

data = {
  :body=>noescape { "I can insert new line <br>with escape { ... } <br>But it may be dangerous" }
}

tmpl.expand(STDOUT, data) # <p>I can insert new line <br>with escape { ... } <br>But it may be dangerous</p>
puts

data = {
  # The attacker expected amrita to print <p yyy=""></p>XSS attack<p>But amrita sanitize it!</p>
  :body=>a(:yyy=>%q["></p>XSS attack here<p]) { "But amrita sanitize it!" }
}
tmpl.expand(STDOUT, data) # <p yyy="&quot;&gt;&lt;/p&gt;XSS attack here&lt;p">But amrita sanitize it!</p>
puts

tmpl = TemplateText.new %q[<a id=body>href is treated in a special way</a>]
data = {
  :body=>a(:href=>%q[javascript:alert('hello')])
}
tmpl.expand(STDOUT, data) # <a href="">href is treated in a special way</a>
puts

description

text

The dangerous characters for xhtml/html text (<>&) are escaped.

"<abc>" => "&lt;abc&gt;"

attribute value

The dangerous characters for attribute value (<>&"') are escaped.

special attribute value for URL

These attribute should be treated in another way because they would have a URL value

for detail see tag.rb.

The value for them will be checked in more strict rule.

The values that dose not match to these rules are replaced with nil and printed like <a href="">....</a>

You can confiture which attribute should be treated as URL by defineing setup_taginfo method like this.

t = TemplateFile.new ...

def t.setup_taginfo
  ret = TagInfo.new
  ret[:aaa].set_url_attr(:bbb)
  ret
end

Then bbb attribute of aaa element (<aaa bbb='...'>) is sanitized as url.

turn sanitizing off

You can turn this feature off by providing a Amrita::SanitizedString object as model data.

t = TemplateText.new '<p id="a">sample_text</p>'
t.expand(STDOUT, { :a=>"<xxx>" })                  # => <p>&lt;xxx&gt;</p>
t.expand(result, { :a=>SanitizedString["<xxx>"] }) # => <p><xxx></p>

You should be careful to sanitize it in your own way when you pass it to amrita as SanitizedString.

There is another way to disable this feature. If you wrapped model data by escape {...}, text will be keeped with no change.