aurita-gui 0.3.1 → 0.3.2

data/TODO

@@ -2,6 +2,9 @@
 - Implement <fieldset>
 - Implement <optgroup>
 
+- Fixme: Setting values only works after all elements have been added 
+         (values won't be set for elements added after form.values=)
+
 - Implement element.sibling[:dom_id] --> element
 - Implement XPath1.0 method (parent, sibling, descendant, following ...)
 

data/aurita-gui.gemspec

@@ -14,7 +14,7 @@ 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.3.1'
+  s.version = '0.3.2'
   s.author = 'Tobias Fuchs'
   s.email = 'fuchs@atomnode.net'
   s.date = Time.now

data/lib/aurita-gui/element.rb

@@ -42,6 +42,19 @@ module GUI
   # by any derived class like Aurita::GUI::Form or 
   # Aurita::GUI::Table. 
   #
+  # == Notes
+  #
+  # Double-quotes in tag parameters will be escaped 
+  # when rendering to string. 
+  #
+  #   e = Element.new(:onclick => 'alert("message");')
+  #
+  # The value of parameter :onclick does not change, 
+  # but will be escaped when rendering: 
+  #
+  #   e.onclick == 'alert("message");'
+  #   e.to_s    == '<div onclick="alert(\"message\");"></div>'
+  #
   class Element
     
     @@element_count = 0
@@ -85,11 +98,11 @@ module GUI
 
     # Return DOM id of this element. 
     def dom_id
-      @attrib[:id]
+      @attrib[:id] if @attrib
     end
     # Set DOM id of this element. 
     def dom_id=(value)
-      @attrib[:id] = value
+      @attrib[:id] = value if @attrib
     end
 
     # Render this element to a string and append another 
@@ -168,7 +181,7 @@ module GUI
         end
         if !value.nil? then
           value = value.to_s
-          attrib_string << ' ' << name.to_s + '="' << value + '"'
+          attrib_string << ' ' << name.to_s + '="' << value.gsub('"','\"') + '"'
         end
       }
       
@@ -188,6 +201,29 @@ module GUI
     def each(&block)
       @content.each(&block)
     end
+
+    def css_classes
+      css_classes = @attrib[:class]
+      if css_classes.kind_of? Array
+        css_classes.flatten! 
+      elsif css_classes.kind_of? String
+        css_classes = css_classes.split(' ') 
+      else # e.g. Symbol
+        css_classes = [ css_classes ]
+      end
+      css_classes.collect { |c| c.to_sym if c }
+      return css_classes
+    end
+
+    def add_class(css_class_name)
+      @attrib[:class] = (css_classes << css_class_name.to_sym)
+    end
+
+    def remove_class(css_class_name)
+      classes = css_classes
+      classes.delete(css_class_name.to_sym)
+      @attrib[:class] = classes
+    end
     
   end # class
   

data/lib/aurita-gui/form.rb

@@ -22,23 +22,114 @@ module Aurita
 module GUI
 
 
+  # Default decorator for form fields. 
+  # Decorates single entry of form to <li> element, setting CSS 
+  # classes and DOM ids. 
+  # To use your own field decorator, derive it from Aurita::GUI::Element
+  # (maybe indirectly via one of its derivates) and define its 
+  # constructor to expect a single Form_Field instance. 
+  # The field decorator has to wrap the actual form field. 
+  #
+  # See the source code of Aurita::GUI::Form_Field_Wrapper for a
+  # simple implementation. 
+  #
+  # Tell a form to use a specific field decorator by 
+  #
+  #   the_form.field_decorator = My_Field_Decorator
+  #
+  # To use your own implementation as defaut, overload Form.initialize 
+  # like
+  #
+  #   class My_Form < Aurita::GUI::Form
+  #     def initialize(params={}, &block)
+  #       super(params, &block)
+  #       @field_decorator = My_Field_Decorator
+  #     emd
+  #   end
+  #
+  # Or write a factory (*hint hint*) like: 
+  #
+  #   class Form_Factory
+  #     def self.form(params={}, &block)
+  #       form = Aurita::GUI::Form.new(params, &block)
+  #       form.field_decorator = My_Field_Decorator
+  #       return form
+  #     end
+  #   end
+  #
+  # See also: Form_Content_Wrapper (pretty much the same). 
+  #
   class Form_Field_Wrapper < Aurita::GUI::Element
     attr_accessor :field
 
     def initialize(field)
-      label_params = { :for => field.dom_id, :force_closing_tag => true }
-      label_params[:id] = field.dom_id.to_s + '_label'
-      label = field.label
-      @content = [ HTML.label(label_params) { label }, field ]
+      label_params = false
+      if field.label then
+        label_params = { :for => field.dom_id, :force_closing_tag => true }
+        label_params[:id] = field.dom_id.to_s + '_label' if field.dom_id
+        label = field.label
+        @content = [ HTML.label(label_params) { label }, field ]
+      else 
+        @content = field
+      end
+      css_classes = field.class.to_s.split('::')[-1].downcase + '_wrap form_field' 
+      css_classes << ' required' if field.required?
+      css_classes << ' invalid' if field.invalid?
       params = { :tag => :li, 
                  :content => @content, 
                  :id => field.dom_id + '_wrap', 
-                 :class => field.class.to_s.split('::')[-1].downcase + '_wrap form_field' }
+                 :class => css_classes }
       super(params)
     end
 
   end
 
+  # Default decorator for form contents (list of form fields). 
+  # Decorates all entries of form to <ul> element, setting CSS 
+  # class 'form_field'.
+  # To use your own field decorator, derive it from Aurita::GUI::Element
+  # (maybe indirectly via one of its derivates) and define its 
+  # constructor to expect a list of Form_Field instances as 
+  # content attribute (either in params or as block). 
+  # The content decorator has to wrap the actual array of form fields. 
+  #
+  # See the source code of Aurita::GUI::Form_Content_Wrapper for a
+  # simple implementation. 
+  #
+  # Tell a form to use a specific content decorator by 
+  #
+  #   the_form.content_decorator = My_Content_Decorator
+  #
+  # To use your own implementation as defaut, overload Form.initialize 
+  # like
+  #
+  #   class My_Form < Aurita::GUI::Form
+  #     def initialize(params={}, &block)
+  #       super(params, &block)
+  #       @content_decorator = My_Content_Decorator
+  #     emd
+  #   end
+  #
+  # Or write a factory (*hint hint*) like: 
+  #
+  #   class Form_Factory
+  #     def self.form(params={}, &block)
+  #       form = Aurita::GUI::Form.new(params, &block)
+  #       form.content_decorator = My_Content_Decorator
+  #       return form
+  #     end
+  #   end
+  #
+  # See also: Form_Field_Wrapper (pretty much the same). 
+  # 
+  class Form_Content_Wrapper < Aurita::GUI::Element
+    def initialize(params={}, &block)
+      params[:tag]     = :ul
+      params[:class]   = :form_fields
+      super(params, &block)
+    end
+  end
+
   # Usage examples: 
   #
   #   form = Form.new(:method   => :put  # default: :post
@@ -174,23 +265,43 @@ module GUI
   #
   #   puts form.to_s
   #
+  # === Further customization
+  #
+  # The default form decorators (Form_Field_Wrapper and 
+  # Form_Content_Wrapper) do their best to guess DOM ids 
+  # and CSS classes. In case you want to implement your
+  # own decorators - e.g. in case you don't want any 
+  # 'guessed' CSS classes at all - you can overwrite them 
+  # via 
+  #
+  #   the_form.field_decorator = My_Field_Decorator
+  #
+  # and
+  #
+  #   the_form.content_decorator = My_Content_Decorator
+  #
+  # See documentation to Form_Field_Wrapper and 
+  # Form_Content_Wrapper for instructions on how to 
+  # implement custom form decorators. 
   #
   class Form < Element
 
-    attr_accessor :method, :target, :action, :fields, :elements, :element_map, :values
+    attr_accessor :method, :target, :action, :fields, :elements, :element_map, :values, :field_decorator, :content_decorator
   
-    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
+    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
       @custom_fields = false
+      @field_decorator   = Aurita::GUI::Form_Field_Wrapper
+      @content_decorator = Aurita::GUI::Form_Content_Wrapper
       if block_given? then
         yield.each { |e| add(e) }
       end
@@ -251,10 +362,12 @@ module GUI
     # TODO: Should overwrite previous field element 
     # with same field name. 
     def add(form_field_element)
+      field_name = form_field_element.name.to_s
+      form_field_element.value = @values[field_name] unless form_field_element.value.to_s != ''
       if !form_field_element.dom_id then
-        form_field_element.dom_id = form_field_element.name.to_s.gsub('.','_')
+        form_field_element.dom_id = field_name.gsub('.','_')
       end
-      @element_map[form_field_element.name.to_s] = form_field_element
+      @element_map[field_name] = form_field_element
       @elements << form_field_element
       @content = false # Invalidate
     end
@@ -342,7 +455,7 @@ module GUI
           if element.kind_of? Aurita::GUI::Hidden_Field then
             @content << element
           else
-            @content << Form_Field_Wrapper.new(element)
+            @content << @field_decorator.new(element)
           end
         end
       }
@@ -353,7 +466,8 @@ module GUI
           @content << element.to_hidden_field()
         end
       }
-      @content = HTML.ul(:class => :form_fields) { @content }
+      fields_id = dom_id().to_s+'_fields' if dom_id()
+      @content = @content_decorator.new(:id => fields_id) { @content }
       return @content
     end
 

data/lib/aurita-gui/form/form_field.rb

@@ -6,12 +6,34 @@ require('aurita-gui/form/form_error')
 module Aurita
 module GUI
 
-  # Class Form_Field is an abstract base class for 
-  # built-in form fields (Input_Field, Hidden_Field, 
+  # Class Form_Field is an abstract base class for built-in
+  # form fields (Input_Field, Hidden_Field, 
   # Radio_Field, Checkbox_Field, Select_Field, 
   # Textarea_Field) or any custom form field type. 
-  # It is a wrapper for GUI::Element, extending it 
-  # by parameters @name, @label and @value. 
+  # It is a wrapper for GUI::Element, extending it by
+  # parameters @name, @label and @value. 
+  #
+  # Form_Field can be used directly as a decorator for any
+  # instance of Element. 
+  # This is useful in case you want to add GUI component
+  # to a form that is not derived from Form_Field itself. 
+  # To do so, pass an Element instance to the constructor's
+  # block. 
+  # Note that in any case, a Form_Field instance requires 
+  # the :name attribute, even if this doesn't make 
+  # sense at first glance when not adding a 'real' form
+  # field. This is necessary as it could not be accessed 
+  # after adding it to the form otherwise. 
+  #
+  # Example: 
+  #
+  #   button = Button.new(:onclick => 'submit();') { 'OK' }
+  #   button_field = Form_Field.new(:name => :submit_button) { button }
+  #   form.add(button_field)
+  #
+  #
+  # In common cases, you won't use Form_Field directly, 
+  # but one of it's derivates. 
   #
   # Usage: 
   #
@@ -65,20 +87,28 @@ module GUI
   #
   #   i.editable! 
   #
+  # You can also store an expected data type in an Form_Field. 
+  # This is just for convenience for e.g. form generators. 
+  # So far, Form_Field@data_type won't be interpreted by 
+  # any part of Aurita::GUI. 
+  #
   class Form_Field < Element
 
-    attr_accessor :type, :form, :label, :value, :required, :hidden
+    attr_accessor :type, :form, :label, :value, :required, :hidden, :data_type, :invalid, :hint
 
-    def initialize(params)
+    def initialize(params, &block)
       # @value  = params[:value]
       raise Form_Error.new('Must provide parameter :name for ' << self.class.to_s) unless params[:name]
-      @form     = params[:parent]
-      @form   ||= params[:form]
-      @label    = params[:label]
+      @form      = params[:parent]
+      @form    ||= params[:form]
+      @label     = params[:label]
       # Get value from params unless set by derived constructor: 
-      @value    = params[:value] unless @value 
-      @required = params[:required]
-      @hidden   = params[:hidden]
+      @value     = params[:value] unless @value 
+      @required  = params[:required]
+      @hidden    = params[:hidden]
+      @data_type = params[:data_type]
+      @invalid   = params[:invalid]
+      @hint      = params[:hint]
       # Do not delete parameter value, as it is a 
       # standard for <input> elements. 
       # Field types not supporting the value attribute
@@ -90,7 +120,14 @@ module GUI
       params.delete(:label)
       params.delete(:required)
       params.delete(:hidden)
+      params.delete(:data_type)
+      params.delete(:invalid)
+      params.delete(:hint)
       params[:parent] = @form
+      if block_given? then 
+        @element = yield
+        params[:content] = @element
+      end
       super(params)
     end
 
@@ -103,7 +140,8 @@ module GUI
 
     # Virtual method. 
     def element
-      raise Form_Error.new('Cannot render abstract class Form_Field')
+      raise Form_Error.new('Cannot render abstract class Form_Field') unless @element
+      @element
     end
 
     # Render this form field element to a 
@@ -160,6 +198,25 @@ module GUI
       end
     end
 
+    # Mark field element as invalid (e.g. missing value). 
+    def invalid!
+      @invalid = true
+      add_class(:invalid)
+    end
+    # Whether this field element is marked as invalid. 
+    def invalid? 
+      @invalid == true
+    end
+    # Set :invalid flag (true | false). 
+    def invalid=(is_invalid)
+      @invalid = is_invalid
+      if is_invalid then 
+        add_class(:invalid) 
+      else 
+        remove_class(:invalid) 
+      end
+    end
+
     # Set field element to disabled mode. 
     # See Aurita::GUI::Form for more information 
     # on rendering modes. 
@@ -225,31 +282,6 @@ module GUI
       (@hidden == true)
     end
 
-  protected
-
-    def css_classes
-      css_classes = @attrib[:class]
-      if css_classes.kind_of? Array
-        css_classes.flatten! 
-      elsif css_classes.kind_of? String
-        css_classes = css_classes.split(' ') 
-      else # e.g. Symbol
-        css_classes = [ css_classes ]
-      end
-      css_classes.collect { |c| c.to_sym if c }
-      return css_classes
-    end
-
-    def add_class(css_class_name)
-      @attrib[:class] = (css_classes << css_class_name.to_sym)
-    end
-
-    def remove_class(css_class_name)
-      classes = css_classes
-      classes.delete(css_class_name.to_sym)
-      @attrib[:class] = classes
-    end
-
   end # class
 
 

data/spec/form.rb

@@ -0,0 +1,28 @@
+
+require('rubygems')
+require('aurita-gui/form')
+
+include Aurita::GUI
+
+describe Aurita::GUI::Form, "basic rendering" do
+  before do
+    @form = Form.new()
+    @text_field = Input_Field.new(:name => :textfield)
+  end
+
+  it "should probvide method #add to add form fields" do
+    @form.add(@text_field)
+  end
+
+  it "should allow access to form fields by index" do
+    text_field = Input_Field.new(:name => :compare_me)
+    @form.add(text_field)
+    @form.elements[0].should == text_field
+  end
+
+  it "should wrap form fields as list elements (<li>...</li>)" do
+    @form.add(@text_field)
+    @form.to_s.should == '<form><ul class="form_fields"><li class="input_field_wrap form_field" id="textfield_wrap"><input type="text" name="textfield" id="textfield" /></li></ul></form>'
+  end
+
+end

data/spec/html.rb

@@ -36,4 +36,10 @@ describe Aurita::GUI::HTML, "basic rendering" do
     @e.to_s.should == '<div class="outer"><h2 id="header">Header</h2><p id="content">Altered</p></div>'
   end
 
+  it "should escape double-quotes in tag parameters" do
+    e = Element.new(:onclick => 'alert("message");')
+    e.onclick.should == 'alert("message");'
+    e.to_s.should == '<div onclick="alert(\"message\");"></div>'
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: aurita-gui
 version: !ruby/object:Gem::Version 
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors: 
 - Tobias Fuchs
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-01-15 00:00:00 +01:00
+date: 2009-01-20 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -58,6 +58,7 @@ files:
 - lib/aurita-gui/form/input_field.rb
 - lib/aurita-gui/form/date_field.rb
 - spec/;
+- spec/form.rb
 - spec/html.rb
 - spec/element.rb
 has_rdoc: true