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 800 lines of code tagz.rb adds
  an html/xml/sgml 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.

FEATURES

  - use as a library or mixin

  - simple, clean and consistent mark-up that is easy to visually
    distinguish from other ruby methods

  - auto-compatibility with rails/actionview

  - ability to independently open and close tagz in markup

  - intelligent auto-escaping of both attributes and content for both html
    and xml

  - validate your html/xml with 'ruby -c' syntax check

  - generally bitchin

  - no lame method_missing approach that prevents tagz like 'type' from being
    generated

  - easy generation of xml with full namespace support that 'just does the 
    right thing'

  - generate xml processing instructions

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

XML NAMESPACES

  using multiple namespaces that you predefine so you get the prefixes
  you expect.  If you don't care what they are, then you don't need the
  #tagz_register_namespace calls.  The right things will just happen
  anyway (see the last example).

    NSD = "D:"
    NSR = "http://ns.example.com/boxschema"

    tagz_register_namespace("D", NSD)
    tagz_register_namespace("R", NSR)

    tagz(:xmlns => NSD) {
      propfind_ {
        prop_ {
          tagz(:xmlns => NSR) {
            bigbox_!
            author_!
            DingALing_!
            Random_!
          }
        }
      }
    }.to_xml

  using namespaces you explicitly include on a node

    feed_("xmlns:a" => "http://www.w3.org/2005/Atom") {
      title_ "..."
      link_!(:href => "http://...")
      updated_ "..."
      author_ {
        name_ "..."
      }
      id_ "..."
      entry_ {
        title_ "..."
        link_!(:href => "http://...")
        id_ "..."
        updated_ "..."
        summary_ "..."
      }
    }.to_xml

  same with defining a default namespace

    feed_("xmlns" => "http://www.w3.org/2005/Atom") {
      title_ "..."
      link_!(:href => "http://...")
      updated_ "..."
      author_ {
        name_ "..."
      }
      id_ "..."
      entry_ {
        title_ "..."
        link_!(:href => "http://...")
        id_ "..."
        updated_ "..."
        summary_ "..."
      }
    }.to_xml

  auto generation of a prefix based on just specifying the namespace URI

    tagz(:xmlns => "AUTOGENME:") {
      root_ {
        child1_ {
          child2_ "Look, Ma!  No hands!!"
        }
      }
    }.to_xml

  pick-a-mix approach with multiple levels of nested namespaces

    root_("xmlns:a" => NSA) {
      a_child1_ {
        a_child2_ {
          tagz(:xmlns => NSB) {
            b_child1_!
            b_child2_ "hello"
            b_child3_ {
              b_child4_ "some content"
            }
          }
        }
        a_child2_ {
          tagz(:xmlns => NSB) {
            b_child1_ "content1"
            b_child2_ "content2"
            b_child3_!
          }
        }
      }
    }.to_xml

XML PROCESSING INSTRUCTIONS

  support for simple processing instructions

    tagz_?("xml-stylesheet", :href => "common.css")
    html_ {
      ...
    }

  support for multiple processing instructions and namespaces

    puts tagz {
      tagz_?("xml-stylesheet", :href=>"common.css")
      tagz_?("xml-stylesheet", :href=>"default.css", :title=>"...")
      tagz_?("xml-stylesheet", :alternate=>"yes", :href=>"alt.css", :title=>"...")
      tagz_?("xml-stylesheet", :href=>"single-col.css", :media=>"...")
      html_(:xmlns => "http://www.w3.org/1999/xhtml") {
        head_ {
          title_ "Example with xml-styleshet processing instructions"
        }
        body_ "..."
      }
    }.to_xml

  support crazy MS content management systems and autogenerate some 
  xml namepaces

    puts tagz {
      tagz_?("mso-infoPathSolution", :solutionVersion => "...")
      tagz_?("mso-application", :progid => "...")
      myFields_("xmlns:my" => "http://...") {
        field1_ "data"
        field2_!
        container1_ {
          tagz(:xmlns => NSB) {
            nsb1_ "hello"
            nsb2_ {
              nsb3_ "xyzzy"
            }
          }
        }
        field3_ "special field"
      }
    }.to_xml

INSTALL

  gem install tagz

URIS

  http://github.com/ahoward/tagz/tree/master
  http://rubyforge.org/projects/codeforpeople

HISTORY
  10.0.0
    - Added XML namespace support

    - Added XML processing instruction support
    
    - Fixed some minor bugs with empty tags and root tags with dashes

    - added :tagz_reset option to reset the document

  7.0.0
    - * IMPORTANT * NOT BACKWARD COMPATIBLE (thus version bump)
    the tagz functionality itself has not changed, but the defaults for
    excaping have!  now tagz will escape attributes, but NOT content, in the
    default mode.  you can easily configure something else with

      Tagz.escape!(:content => true, :attributes => true)

    which would be like saying

      Tagz.xml_mode!

    or

      Tagz.escape!(:content => false, :attributes => true)

    which would be like saying

      Tagz.html_mode!

    to repeat, the default is 'Tagz.html_mode!'

  6.0.0 
    - reorganize lib to avoid dumping a few constants into the includee - aka
    don't absolutely minimize namespace pollution. there is now reason to
    thing this version shouldn't be backwards compat - i bumped the version
    just in case

  5.1.0
    - attribute/content auto-escaping can be turned off with

        Tagz.i_know_what_the_hell_i_am_doing!

      and turned back on with

        Tagz.i_do_not_know_what_the_hell_i_am_doing!

      attribute and content escaping can be configured individually too. see
      tests for examples


      thanks Dan Fitzpatrick

    - << and concat escape (if configured) while puts and push and write do not

      thanks JoelVanderWerf

  5.0.0
    - introduce better escaping for attributes using xchar.rb approach
    - indroduce smart escaping for content
    - make Tagz.globally kick ass more hard
    - note that this version is not backward compatibile if you were relying
      on tagz never escaping any content should be an ok upgrade for most
      applications

  4.6.0
    - fix a bug with self closing tagz that had crept in 1.0.0 -> 4.2.0.  thx
      jeremy hinegardner

    - added tests from 1.0.0 back into svn

  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