::Html

Cheri::Html

Documentation TBD

To include:

require 'rubygems'
require 'cheri/html'
 ...
include Cheri::Html
Note that inclusion at the top level is not recommended.

Options:

html[:format]        #=> output formatted with line-feeds only
html[:format=>true] 
  
html[:indent]        #=> output indented by 2 spaces per level
html[:indent=>nnn]   #=> output indented by nnn spaces per level
  
html[:margin=>nnn]   #=> output indented by margin
                     #=> (in addition to :indent)
  
html[:esc]           #=> output will be escaped
html[:esc=>true]     #=>(off by default for performance) 
                 

# declare tag aliases  
html[:alias=>[:alias1,:name1,:alias2,:name2...]]

# declare attribute aliases  
html[:attr=>[:alias1,:attr1...]]

# include !DOCTYPE declaration
html[:doctype]
html[:doctype=>true]

# use strict doctype declaration
html[:strict]
html[:strict=>true]
Options specified using html[opts] apply to all threads for an instance.
Options specified using html(opts) apply only to the current thread/scope:
# example
html[:indent=>2,:esc=>false]
@out = html { body {
  # nothing escaped at this level...
  text 'this text not escaped'

  # ...unless explicitly escaped
  esc 'this text will be escaped'

  table{
    tr {
      html(:esc) {
        # all text/attributes escaped in this scope
        td 'this text will be escaped', :align=>:left
        td b(i('as will this text')), ' and <this> too', :class=>'>oops'
}}}}}
The result of an html block will be one of several types of object, depending on the tags used and how they are invoked. The result object can be coerced to a String, directly by calling its to_s method, or indirectly by using << to append it to a String or IO stream. The to_s method also takes an optional String/stream parameter; when writing to a stream (or an existing string), this is the most efficient way to render HTML.
# example
html[:indent,:doctype]

@result = html{body{table{tr{td 'Hi'}}}}

puts @result           #=> HTML
@result.to_s           #=> HTML
a_string << @result    #=> appends HTML
a_stream << @result    #=> appends HTML
@result.to_s(a_string) #=> appends HTML more efficiently
@result.to_s(a_stream) #=> appends HTML more efficiently

# result:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <body>
    <table>
      <tr>
        <td>Hi</td>
      </tr>
    </table>
  </body>
</html>
To omit the <html></html> tag, use html as the receiver for the initial element:
html.p{b{'Howdy'}}
# result
<p>
  <b>Howdy</b>
</p>
To create escaped HTML, viewable in a web page (as I have for these examples), wrap the HTML in an esc (or esc!) block:
html.esc! {
  html {body {table {tr {td 'Hi'}}}}
}
#result:
&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd"&gt;
&lt;html&gt;
  &lt;body&gt;
    &lt;table&gt;
      &lt;tr&gt;
        &lt;td&gt;Hi&lt;/td&gt;
      &lt;/tr&gt;
    &lt;/table&gt;
  &lt;/body&gt;
&lt;/html&gt;
# (note that I enclosed it in two esc blocks to create this example)

Complete Cheri::Html documentation coming soon!

Copyright © 2007-2009 Bill Dortch