aurita-gui 0.1.0

data/History.txt

@@ -0,0 +1,7 @@
+=== 0.1.0 / 2009-01-07
+
+* First commit. 
+* Added base classes Element and HTML. 
+* Added API for forms. 
+* Added API for tables. 
+

data/LICENSE

@@ -0,0 +1,19 @@
+
+Copyright (c) 2008-2009 Tobias Fuchs (fuchs@wortundform.de)
+Aurita::GUI is a core module of Aurita, Copyright (c) 2004-2009 Tobias Fuchs (fuchs@wortundform.de)
+
+(MIT Licence)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated 
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation 
+the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and 
+to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of 
+the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO 
+THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
+DEALINGS IN THE SOFTWARE.

data/aurita-gui.gemspec

@@ -0,0 +1,37 @@
+
+require 'rake'
+
+spec = Gem::Specification.new { |s|
+
+  s.name = 'aurita-gui' 
+  s.rubyforge_project = 'aurita'
+  s.summary = 'Dead-simple object-oriented creation of HTML elements, including forms, tables and many more. '
+  s.description = <<-EOF
+Aurita::GUI provides an intuitive and flexible API for object-oriented creation 
+of primitive and complex HTML elements, such as tables and forms. 
+It is a core module of the Aurita application framework, but it can be used 
+as stand-alone library in any context (such as rails). 
+As there seems to be a lack of ruby form generators, i decided to release this 
+part of Aurita in a single gem with no dependencies. 
+  EOF
+  s.version = '0.1.0'
+  s.author = 'Tobias Fuchs'
+  s.email = 'fuchs@atomnode.net'
+  s.date = Time.now
+  s.files = '*.rb'
+# s.add_dependency('postgres', '>= 0.1')
+  s.files = FileList['*', 
+                     'lib/*', 
+                     'lib/aurita-gui/*', 
+                     'lib/aurita-gui/form/*', 
+                     'bin/*', 
+                     'test/*'].to_a
+
+  s.has_rdoc = true
+  s.rdoc_options << '--title' << 'Aurita::GUI' <<
+                    '--main' << 'Aurita::GUI::HTML' <<
+                    '--line-numbers'
+
+  s.homepage = 'http://aurita.wortundform.de/'
+
+}

data/lib/aurita-gui.rb

@@ -0,0 +1,6 @@
+
+require('aurita-gui/element')
+require('aurita-gui/html')
+require('aurita-gui/form')
+require('aurita-gui/table')
+

data/lib/aurita-gui/button.rb

@@ -0,0 +1,85 @@
+
+require('aurita-gui/element')
+
+module Aurita
+module GUI
+
+  # Specialization of Aurita::GUI::Element, extending 
+  # it by @icon to display in the button. 
+  #
+  # Usage: 
+  #
+  #   b = Button.new(:type => :submit,             # default is :button
+  #                  :icon => '/path/to/icon.png', # default is no icon
+  #                  :onclick => 'alert('button clicked'); ") { 
+  #         'click me' 
+  #       }
+  #   
+  # Change button text: 
+  #
+  #   b.content = 'Custom button text'
+  #
+  # Disable icon again: 
+  #
+  #   b.icon   = false
+  #
+  class Button < Element
+    attr_accessor :icon
+
+    def initialize(params, &block)
+      params[:tag]  = :button
+      params[:type] = :button unless params[:type]
+      @icon         = params[:icon]
+      params.delete(:icon)
+      super(params, &block)
+    end
+
+    def content
+      if @icon then
+        return [ HTML.img(:src => @icon), @content ]
+      end
+      return @content
+    end
+
+  end
+
+  # Specialization of Aurita::GUI::Element for 
+  # submit buttons. Set @tag to :input, @type to :submit. 
+  # Block argument will be used as button label (:value)
+  # Example: 
+  #
+  #   b = Submit_Button.new(:class => :css_class) { 'click me' }
+  #
+  class Submit_Button < Element
+    def initialize(params, &block)
+      params[:tag]  = :input
+      params[:type] = :submit unless params[:type]
+      if block_given? then
+        params[:value] = yield
+      end
+      super(params)
+    end
+  end
+
+  # Specialization of Aurita::GUI::Element for 
+  # submit buttons. Set @tag to :input, @type to :reset. 
+  # Block argument will be used as button label (:value)
+  # Example: 
+  #
+  #   b = Reset_Button.new(:class => :css_class) { 'click me' }
+  #
+  # Note that reset buttons in forms are considered 
+  # bad style in terms of usability. 
+  class Reset_Button < Element
+    def initialize(params, &block)
+      params[:tag]  = :input
+      params[:type] = :reset unless params[:type]
+      if block_given? then
+        params[:value] = yield
+      end
+      super(params)
+    end
+  end
+
+end
+end

data/lib/aurita-gui/element.rb

@@ -0,0 +1,161 @@
+
+module Aurita
+module GUI
+    
+  # GUI::Element is the base class for any rendering 
+  # implementation. 
+  # It consists of the following members: 
+  #
+  #   * @tag: The HTML tag to render. 
+  #   * @attrib: A hash storing tag attributes, like 
+  #              { :href => '/link/to/somewhere' }
+  #   * @content: Content this element is wrapping. 
+  #               Content can be set in the constructor 
+  #               via parameter :content or using a 
+  #               block or by #content and #content=. 
+  #
+  # Most methods invoked on an Element instance are 
+  # redirected to return or set a tag attribute. 
+  # Example: 
+  #
+  #   link = Element(:tag => :a) { 'klick me' }
+  #   link.href = '/link/to/somewhere'
+  #
+  # Same as 
+  #
+  #   link = Element(:tag => :a, 
+  #                  :content => 'click me', 
+  #                  :href => '/link/to/somewhere')
+  #
+  # An Element instance can wrap one or more other 
+  # elements: 
+  #
+  #   image_link = Element.new(:tag => :a, :href => '/link/') { 
+  #                  Element.new(:tag => :img, :src => '/an_image.png')
+  #                }
+  #
+  # In case an element has no content, it will render 
+  # a self-closing tag, like <img ... />. 
+  #
+  # In most cases you won't use class Element directly, 
+  # but by using a factory like Aurita::GUI::HTML or 
+  # by any derived class like Aurita::GUI::Form or 
+  # Aurita::GUI::Table. 
+  #
+  class Element
+    
+    @@element_count = 0
+    
+    attr_accessor :attrib, :type, :content, :parent, :tag
+    
+    def initialize(params={}, &block) 
+      @@element_count += 1
+      @id      = @@element_count
+      @parent  = params[:parent]
+      params.delete(:parent)
+
+      params[:tag] = :div if params[:tag].nil?
+
+      if block_given? then
+        @content = yield
+      else
+        @content = params[:content].to_s
+      end
+      params.delete(:content)
+      @tag     = params[:tag]
+      params.delete(:tag)
+      # params[:id] = self.class.to_s.split('::')[-1].downcase + '_' << @@element_count.to_s if params[:id].nil?
+      params[:onclick] << ';' unless params[:onclick].nil? or params[:onclick].include?(';')
+      
+      @attrib = params
+      # @attrib[:id] = @attrib[:id].to_s 
+      
+    end
+
+    # Return DOM id of this element. 
+    def dom_id
+      @attrib[:id]
+    end
+    # Set DOM id of this element. 
+    def dom_id=(value)
+      @attrib[:id] = value
+    end
+
+    # Render this element to a string and append another 
+    # element. 
+    def +(other)
+      return string << other.string if other.kind_of? Element
+      return string << other
+    end
+    alias << +
+
+    # Redirect methods to setting or retreiving tag 
+    # attributes. 
+    def method_missing(meth, value=nil)
+      return @attrib[meth] unless value or meth.to_s.include? '='
+      @attrib[meth.to_s.gsub('=','').intern] = value
+    end
+
+    # Define explicitly so built-in method #type 
+    # is not invoked instead
+    def type=(type)
+      @attrib[:type] = type
+    end
+    # Alias definition for #dom_id=(value)
+    # Define explicitly so built-in method #id
+    # is not invoked instead
+    def id=(value)
+      @attrib[:id] = value
+    end
+    # Alias definition for #dom_id()
+    def id
+      @attrib[:id]
+    end
+
+    # Do not redirect random access operators. 
+    def [](a)
+      raise ::Exception.new('Undefined method [] for ' << self.class.to_s)
+    end
+    # Do not redirect random access operators. 
+    def []=(a,b)
+      raise ::Exception.new('Undefined method []= for ' << self.class.to_s)
+    end
+
+    # Static helper definition for clearing 
+    # CSS floats. 
+    def clear_floating
+      '<div style="clear: both;" />'
+    end
+
+    # Render this element to a string. 
+    def string
+      attrib_string = ''
+      @attrib.each_pair { |name,value|
+        if value.instance_of?(Array) then
+          value = value.join(' ')
+        elsif
+          value.instance_of?(TrueClass) then
+          value = name
+        end
+        if !value.nil? then
+          value = value.to_s
+          attrib_string << name.to_s + '="' << value + '" '
+        end
+      }
+      
+      if content.to_s != '' then
+        '<' << @tag.to_s << ' ' << attrib_string << '>' << "\n" << 
+        content.to_s + 
+        '</' << @tag.to_s << '>' << "\n" 
+      else
+        '<' << @tag.to_s << ' ' << attrib_string << '/>' << "\n" 
+      end
+      
+    end
+    alias to_s string
+    
+  end # class
+  
+end # module
+end # module
+

data/lib/aurita-gui/form.rb

@@ -0,0 +1,232 @@
+
+require('aurita-gui/element')
+require('aurita-gui/html')
+require('aurita-gui/form/form_field')
+require('aurita-gui/form/form_error')
+require('aurita-gui/form/input_field')
+require('aurita-gui/form/hidden_field')
+require('aurita-gui/form/options_field')
+require('aurita-gui/form/select_field')
+require('aurita-gui/form/radio_field')
+require('aurita-gui/form/checkbox_field')
+require('aurita-gui/form/fieldset')
+require('aurita-gui/form/textarea_field')
+require('aurita-gui/form/date_field')
+require('aurita-gui/form/datetime_field')
+require('aurita-gui/form/file_field')
+
+module Aurita
+module GUI
+
+
+  class Form_Field_Wrapper < Aurita::GUI::Element
+    attr_accessor :field
+
+    def initialize(field)
+      label_params = { :for => field.dom_id }
+      label_params[:id] = field.dom_id.to_s + '_label' 
+      @content = [ HTML.label(label_params) { field.label }, field ]
+      params = { :tag => :li, 
+                 :content => @content, 
+                 :id => field.dom_id + '_wrap', 
+                 :class => field.class.to_s.split('::')[-1].downcase + '_wrap form_field' }
+      super(params)
+    end
+
+  end
+
+  class Form < Element
+
+    attr_accessor :method, :target, :action, :fields, :elements, :element_map
+  
+    # Usage examples: 
+    #
+    #   form = Form.new(:method   => :put  # default: :post
+    #                   :action   => '/where/to/send/form/'
+    #                   :onsubmit => "alert('submitting');") { 
+    #     [ 
+    #       Input_Field.new(:name => :description, :label => 'Description'), 
+    #       Select_Field.new(:name => :category, :label => 'Select category')
+    #     ]
+    #   }
+    #   textarea = GUI::Textarea.new(:name => :comment, :label => 'Comment')
+    #   form.add(textarea)
+    #  
+    # In case you want to override the form action (default: /aurita/dispatch), 
+    # use :action_url: 
+    #
+    #   Form.new(:action_url => '/where/to/send/form')
+    # or
+    #   Form.action_url = '/where/to/send/form'
+    #
+    #
+    def initialize(params, &block)
+      @action       = params[:action]
+      @method       = params[:method]
+      @fields       = params[:fields]
+      @values       = params[:values]
+      @method     ||= :post
+      @fields     ||= []
+      @elements     = []
+      @element_map  = {}
+      @values     ||= {}
+      @title        = false
+      if block_given? then
+        yield.each { |e| add(e) }
+      end
+      params.delete(:fields)
+      params.delete(:values)
+      params[:tag]     = 'form'
+      params[:content] = content()
+      super(params)
+    end
+
+    # Returns field element map. 
+    # An element map maps field names to elements of 
+    # this form. 
+    def attributes
+      @element_map
+    end
+
+    # Access form element by index or name (by index if 
+    # parameter is of type Numeric, by name otherwhise)
+    def [](index)
+      return @elements[index] if index.kind_of? Numeric
+      return @element_map[index.to_s] 
+    end
+
+    # Assign / overwrite field element with index form_index. 
+    def []=(index, form_field)
+      @elements[index] = form_field
+      @content = false # Invalidate
+    end
+    
+    # Delete form field with name field_name from 
+    # this form. 
+    def delete(field_name)
+      @element_map.delete(field_name.to_s)
+    end
+
+    # Iterate over form field elements. 
+    # This would add a CSS class to all elements without 
+    # a value: 
+    #
+    #   form.each { |element| 
+    #     element.class = 'missing' unless element.value
+    #   }
+    #
+    def each(&block)
+      @elements.each(&block)
+    end
+
+    # Add form field element to this form. 
+    def add(form_field_element)
+      if !form_field_element.dom_id then
+        form_field_element.dom_id = form_field_element.name.to_s.gsub('.','_')
+      end
+      @element_map[form_field_element.name.to_s] = form_field_element
+      @elements << form_field_element
+      @content = false # Invalidate
+    end
+
+    # Set field configuration. Form fields will be 
+    # rendered in the same order as field names in the
+    # parameter array. 
+    # In case an element's field name is not included
+    # in the array, it will not be rendered. 
+    # Example: 
+    #
+    #   form.fields = [ :name, :description, :date ]
+    #
+    def fields=(attrib_array)
+      @fields = attrib_array.flatten.collect { |fieldname| fieldname.to_s }
+      @elements.each { |field|
+        @element_map[field.name.to_s] = field
+      }
+    end
+    alias set_field_config fields=
+
+    # Set field values for this form. 
+    # Expects hash mapping field names to values. 
+    # Example: 
+    #   
+    #   form.values = { :name => 'Foo', :description => 'Bar', :date => '20081012' }
+    #
+    def values=(value_hash={})
+      @values = value_hash
+    end
+    alias set_values values=
+
+    # Set all elements to readonly rendering mode. 
+    def readonly!
+      @elements.each { |e|
+        e.readonly!
+      }
+    end
+
+    # Return array of field names currently 
+    # available for rendering. 
+    def fields()
+      if !@fields || @fields.length == 0 then
+        @elements.each { |field|
+          @fields << field.name.to_s
+          @element_map[field.name.to_s] = field
+        }
+      end
+      return @fields
+    end
+
+    # Return underlying HTML element instance (HTML.ul), 
+    # without wrapping HTML.form element. 
+    def content
+      # TODO: Provide Fieldset instances
+      @content = []
+      if @title then
+        @content << HTML.h1(:class => :form_title) { @title }
+      end
+      fields().each { |field|
+        element = @element_map[field.to_s]
+        if element then
+          value   = @values[element.name.to_s] 
+          value ||= @values[element.name.to_s.intern] 
+          element.value = value if value
+          if element.kind_of? Aurita::GUI::Hidden_Field then
+            @content << element
+          else
+            @content << Form_Field_Wrapper.new(element)
+          end
+        end
+      }
+      @content = HTML.ul(:class => :form_fields) { @content }
+      return @content
+    end
+
+    # Render this form to an HTML.form instance. 
+    # Wraps result of #content. 
+    def element
+      HTML.form(@params, :content => @content)
+    end
+
+    # Render this form to a string
+    def string
+      element().to_s
+    end
+    alias to_s string
+
+    # Set all form elements to readonly mode. 
+    def readonly! 
+      elements.each { |e|
+        e.readonly! 
+      }
+    end
+    # Set all form elements to editable mode. 
+    def editable! 
+      elements.each { |e|
+        e.editable! 
+      }
+    end
+
+  end
+
+end
+end