sporkmonger / instrument

== Instrument

Homepage::  instrument.rubyforge.org[http://instrument.rubyforge.org/]
Author::    Bob Aman  (mailto:bob@sporkmonger.com)
Copyright:: Copyright © 2008 Day Automation Systems, Inc.
License::   MIT

== Description

Instrument is a simple library for producing dynamically generated "controls"
with various templating languages.

== Features

* Generate controls with Erb, Haml, Markaby, or XML Builder.  Instrument
  doesn't care what template language you prefer.
* Output XHTML, XML, or JSON.  Instrument doesn't care what your output
  format is.

== Example Usage

  select_control = SelectControl.new(:name => "base", :selections => [
    {:label => "One", :value => "1"},
    {:label => "Two", :value => "2"},
    {:label => "Three", :value => "3"},
    {:label => "Four", :value => "4"}
  ])
  xhtml_output = select_control.to_xhtml

or

  include Instrument::ControlBuilder
  
  select_control(:name => "base", :selections => [
    {:label => "One", :value => "1"},
    {:label => "Two", :value => "2"},
    {:label => "Three", :value => "3"},
    {:label => "Four", :value => "4"}
  ]).to_xhtml

select_control.rb:

  require "instrument"

  class SelectControl < Instrument::Control
    class Option
      def initialize(label, value)
        @label, @value = label, value
      end
  
      attr_accessor :label
      attr_accessor :value
    end

    def element_id
      return self.options[:id] || self.options[:name]
    end

    def element_name
      return self.options[:name]
    end

    def selections
      if !defined?(@selections) || @selections == nil
        @selections = []
        for selection in self.options[:selections]
          if selection.kind_of?(Hash)
            @selections << Option.new(selection[:label], selection[:value])
          else
            @selections << Option.new(selection, selection)
          end
        end
      end
      return @selections
    end
  end
  
select.xhtml.haml:
  
  %select{:id => element_id, :name => element_name}
    - for selection in selections
      %option{:value => selection.value}
        = selection.label

== Requirements

* Instrument has no explicit dependencies.  If you want to output Haml, you
  will need the Haml library installed.  Same goes for any of the other
  template languages.

== Install

* sudo gem install instrument
* sudo gem install haml (optional)
* sudo gem install erubis (optional)
* sudo gem install markaby (optional)
* sudo gem install builder (optional)