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.<br>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=""></p>XSS attack here<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>" => "<abc>"
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
- href attribute of <a> element
- src attribute of <img> element
- action attribute of <form> element
for detail see tag.rb.
The value for them will be checked in more strict rule.
- They can't have any characters that is not allowd
- They can't have any schemes that is not allowd
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><xxx></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.