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:
<!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>
# (note that I enclosed it in two esc blocks to create this example)
Complete Cheri::Html documentation coming soon!
