= Amrita tour

==  modify attributes of HTML element


=== code and output

code:

  :include: sample/tour/makeurl.rb


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:

  :include: sample/tour/proc.rb

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 <tt><font color...>I love Ruby!</font></tt>.
The output is wrapped by <tt>\<em>....\</em></tt> by <tt>e(:em) { .... }</tt>.

---

== use custom classes for model data


=== code and output

code:

  :include: sample/tour/time.rb


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 <tt><span id="year"></span></tt> get result of
method call <tt>t.yera</tt>: "2002" . Thus the produces the output...

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

Amrita deletes <tt><span></tt> 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

  :include: sample/tour/sanitizer.rb

=== 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

* +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 <tt><a href="">....</a></tt>

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 <tt>escape {...} </tt>, text will be keeped with no change.
*USE THIS AT YOUR OWN RISK!!!*

---