File: README — Documentation for tagz (4.4.0)

NAME

tagz.rb

SYNOPSIS

require Tagz

include Tagz.globally

a_(:href => "/foo"){ "bar" }  #=>  <a href="/foo">bar</a>

DESCRIPTION

tagz.rb is generates html, xml, or any sgml variant like a small ninja
running across the backs of a herd of giraffes swatting of heads like a
mark-up weedwacker.  weighing in at less than 200 lines of code tagz.rb adds
an html syntax to ruby that is both unobtrusive, safe, and available
globally to objects without the need for any builder or superfluous objects.
tagz.rb is designed for applications that generate html to be able to do so
easily in any context without heavyweight syntax or scoping issues, like a
ninja sword through butter.

RAILS

in config/environment.rb

  require 'tagz'

in a helper

  def list_of_users
    ul_(:class => 'users'){
      @users.each{|user| li_{ user }}
    }
  end

in a view

  <%=
    table_{ 
      rows.each do |row|
        tr_{
          row.each do |cell|
            td_{ cell }
          end
        }
      end
    }
  %>

in a controller

  def ajax_responder
    text =
      tagz{
        table_{ 
          rows.each do |row|
            tr_{
              row.each do |cell|
                td_{ cell }
              end
            }
          end
        }
      }

    render :text => text
  end

INSTALL

gem install tagz

HISTORY

4.4.0
  - remove dependancy on cgi lib, tagz is now completely standalone

4.3.0
  - detect rails and auto-include into ActionController::Base and include
    globally into ActionView::Base

4.2.0
  - general lib cleanup
  - introduction of dual-mixin technique (Tagz.globally)
  - few small bug fixes
  - ninja tales

SAMPLES

<========< samples/a.rb >========>

~ > cat samples/a.rb

  #
  # in the simplest case tagz generates html using a syntax which safely mixes
  # in to any object
  #

  require 'tagz'
  include Tagz.globally

  class GiraffeModel
    def link
      a_(:href => "/giraffe/neck/42"){ "whack!" }
    end
  end

  puts GiraffeModel.new.link

~ > ruby samples/a.rb

  <a href="/giraffe/neck/42">whack!</a>

<========< samples/b.rb >========>

~ > cat samples/b.rb

  #
  # tagz.rb mixes quite easily with your favourite templating engine, avoiding
  # the need for '<% rows.each do |row| %> ... <% row.each do |cell| %> '
  # madness and other types of logic to be coded in the templating language,
  # leaving templating to template engines and logic and looping to ruby -
  # unencumbered by extra funky syntax
  #

  require 'tagz'
  include Tagz.globally

  require 'erb'

  rows = %w( a b c ), %w( 1 2 3 )

  template = ERB.new <<-ERB
    <html>
      <body>
        <%=

          if rows

            table_{
              rows.each do |row|
                tr_{
                  row.each do |cell|
                    td_{ cell }
                  end
                }
              end
            }

          end

        %>
      </body>
    </html>
  ERB

  puts template.result(binding)

~ > ruby samples/b.rb

    <html>
      <body>
        <table><tr><td>a</td><td>b</td><td>c</td></tr><tr><td>1</td><td>2</td><td>3</td></tr></table>
      </body>
    </html>

<========< samples/c.rb >========>

~ > cat samples/c.rb

  #
  # once you've learned to generate html using tagz you're primed to generate
  # xml too
  #

  require 'tagz'
  include Tagz.globally

  doc =
    xml_{
      giraffe_{ 'large' }
      ninja_{ 'small' }
    }

  puts doc

~ > ruby samples/c.rb

  <xml><giraffe>large</giraffe><ninja>small</ninja></xml>

<========< samples/d.rb >========>

~ > cat samples/d.rb

  #
  # tagz.rb doesn't cramp your style, allowing even invalid html to be
  # generated.  note the use of the 'tagz' method, which can be used both to
  # capture output and to append content to the top of the stack.
  #

  require 'tagz'
  include Tagz.globally

  def header
    tagz{
      html_
        body_(:class => 'ninja-like', :id => 'giraffe-slayer')

        tagz << "\n<!-- this is the header -->\n"
    }
  end

  def footer
    tagz{
      tagz << "\n<!-- this is the footer -->\n"

      body_
        html_
    }
  end

  puts header, footer

~ > ruby samples/d.rb

  <html><body class="ninja-like" id="giraffe-slayer">
  <!-- this is the header -->

  <!-- this is the footer -->
  <body><html>

<========< samples/e.rb >========>

~ > cat samples/e.rb

  #
  # tagz.rb allows a safer method of mixin which requires any tagz methods to be
  # insider a tagz block - tagz generating methods outside a tagz block with
  # raise an error if tagz is included this way.  also notice that the error is
  # reported from where it was raised - not from the bowels of the the tagz.rb
  # lib.
  #

  require 'tagz'
  include Tagz

  puts tagz{
   html_{ 'works only in here' }
  }

  begin
    html_{ 'not out here' }
  rescue Object => e
    p :backtrace => e.backtrace
  end

~ > ruby samples/e.rb

  <html>works only in here</html>
  {:backtrace=>["samples/e.rb:17"]}

<========< samples/f.rb >========>

~ > cat samples/f.rb

  #
  # tagz.rb can generate really compact html.  this is great to save bandwidth
  # but can sometimes make reading the generated html a bit rough.  of course
  # using tidy or the dom inspector in firebug obviates the issue; nevertheless
  # it's sometime nice to break things up a little.  you can use 'tagz << "\n"'
  # or the special shorthand '__' to accomplish this
  #

  require 'tagz'
  include Tagz.globally

  p div_{
    span_{ true }
    __
    span_{ false }  # hey ryan, i fixed this ;-)
    __
  }

~ > ruby samples/f.rb

  "<div><span>true</span>\n<span>false</span>\n</div>"