File: Tour

Tour |
Path: | docs/Tour
Modified: | Wed Nov 06 15:02:26 JST 2002

# 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

- `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>&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. *USE THIS AT YOUR OWN RISK!!!*