kiss 1.7.4 → 1.8

data/lib/kiss/form/field.rb

@@ -2,134 +2,101 @@ require 'kiss/form/field';
 
 class Kiss
   class Form
+    ### Abstract Field Classes ###
+    
+    # Base class for single-value fields.
     class Field
-      dsl_accessor :name, :type, :form, :currency, :label, :no_label, :prompt, :value, :read_only,
-        :ignore, :save, :options, :options_value_key, :options_display_key, :options_display_transform, 
-        :required, :unique, :cancel, :columns, :style, :hidden_join, :html, :other, :other_field, :object, 
-        :format, :display_format, :key, :match, :tip, :statement, :attach_errors, :factor, :digest,
-        :min_value_size, :max_value_size, :choose_here
-      alias_method :option_value_key, :options_value_key
-      alias_method :option_display_key, :options_display_key
-      alias_method :option_display_transform, :options_display_transform
+      CURRENCY_SYMBOLS = {
+        :dollars => '$'
+      }
+      
+      _attr_accessor :errors
+      
+      dsl_accessor(
+        :form,            # (Kiss::Form) form to which this field is attached
+                          
+        :object,          # (Kiss::Model) object which holds data for this field
+        :save,            # (Boolean) true iff field value should be saved to object (default: true)
+                          
+        :name,            # (String) name attribute of field element and input param
+        :key,             # (Symbol) key in object for the data accessed by this field
+        :value,           # (data type depends on format) value of field
+                          
+        :required,        # (Boolean) true iff user must supply a enter/choose for this field (default: false)
+        :format,          # (Symbol) format for validation of field value input (see Kiss::Format)
+        :match,           # (String) name of field whose input value must match this field's value
+        :unique,          # (Boolean) true iff this field's value must be unique for key in the object model
+                          
+        :label,           # (String) label to present before this field in HTML
+        :prompt,          # (String) prompt to present above this field in HTML
+        :tip,             # (String) tip to present following this field in HTML
+        # TODO: Some currencies should be prefixed, while others should be suffixed.
+        :currency,        # (String) currency to present directly before this field in HTML
+        :style,           # (String) style attribute for field element in HTML
+        :html,            # (Hash or String) extra HTML attributes to add to field element
+        :attach_errors,   # (Boolean) if true, display field errors with this field; else at top of form
+        
+        :factor,          # (Numeric) factor to be multiplied by value
+        :digest,          # (Symbol) digest to be applied to value before saving to object          
+        
+        :min_value_size,  # (Numeric) minimum size of field value
+        :max_value_size   # (Numeric) maximum size of field value
+      )
       alias_method :min_value_length, :min_value_size
       alias_method :max_value_length, :max_value_size
       
       def method_missing(method, *args, &block)
         @_form.action.send method, *args, &block
       end
-      
-      def options_keys(value, display)
-        @_options_value_key = value
-        @_options_display_key = display
-      end
-      alias_method :option_keys, :options_keys
     
       def debug(*args)
         @_form.delegate.request.debug(args.first, Kernel.caller[0])
       end
+      
+      class << self
+        _attr_accessor :type
+      end
+      
+      def type
+        self.class.type
+      end
   
       def initialize(form, *args, &block)
+        # call as method to allow subclasses to override
+        self.form = form
+        
         # defaults
-        @_form = form
         @_save = true
         @_currency = nil
-        @_attrs = args.to_attrs
-        @_type = :text
         @_object = @_form.object
-        @_save = true
         @_attach_errors = true
         
-        _instance_variables_set_from_attrs(@_attrs)
+        _instance_variables_set_from_attrs(args.to_attrs)
         instance_eval(&block) if block_given?
         
-        @_errors = []
+        raise 'field must have a name' unless @_name
+        @_name = @_name
+        @_key ||= @_name.to_sym
+        @_label ||= @_name.titleize unless self.is_a?(SubmitField)
         
+        @_errors = []
         @_format = Kiss::Format.lookup(@_format)
-        @_display_format = Kiss::Format.lookup(@_display_format)
-        
-        raise 'field must have a name' unless @_name
-        @_key ||= @_name
-        @_label ||= @_name.titleize unless @_type == :submit
+        @_tip = ((legend = @_format.legend) ? "(#{legend})" : nil) unless defined? @_tip
         
-        # object's value overrides any form field value
-        # form field value is intended as default in case object value is missing
-        if @_object && (value = @_object[@_key.to_sym])
+        # object's value (if present) overrides default form field value
+        if @_object && (value = @_object[@_key])
           @_value = value
         end
         
         if @_currency.is_a?(Symbol)
-          @_currency = case @_currency
-          when :dollars
-            '$'
-          else
-            ''
-          end
+          @_currency = CURRENCY_SYMBOLS[@_currency] || ''
         end
         
-        if @_options
-          if @_options[0].is_a?(Array)
-            @_options_value_key ||= 0
-            (@_options_display_key ||= (@_options[0].size == 1) ? 0 : 1)
-          elsif defined?(Kiss::Model) && @_options[0].is_a?(Kiss::Model)
-            model_klass = @_options[0].class
-            @_options_value_key ||= model_klass.value_column
-            @_options_display_key ||= model_klass.display_column
-          elsif @_options[0].is_a?(Hash)
-            @_options_value_key ||= :id
-            @_options_display_key ||= :name
-          end
-        end
-        
-        @_tip = ((legend = @_format.legend) ? "(#{legend})" : nil) unless defined? @_tip
-        
         @_form.has_required_fields ||= @_required
       end
       
-      def other_field_html
-        return '' unless @_other
-        
-        other_checked = @_value && !option_pairs.any? {|v, d| v == @_value }
-        
-        (@_columns ? '<br/>' : '&nbsp; ') + [
-          input_tag_html(
-            { :value => 'other', :html => { :id => @_name+'.other' } },
-            other_checked ? 'checked' : ''
-          ),
-          @_other[:label] || 'Other',
-          ': ',
-          @_currency.to_s,
-          input_tag_html({
-            :type => :text,
-            :name => @_name+'.other',
-            :value => other_checked ? value_to_s(@_value) : nil,
-            :html => {
-              :onfocus => "document.getElementById('#{@_name}.other').checked = true"
-            }
-          }.merge(@_other))
-        ].join
-      end
-      
-      def column_layout(elements_html)
-        if elements_html.empty?
-          ''
-        elsif @_columns
-          layout_columns = [@_columns, elements_html.size].min
-          num_elements_per_column = ((elements_html.size + layout_columns - 1) / layout_columns).to_i
-          layout_columns = ((elements_html.size + num_elements_per_column - 1) / num_elements_per_column).to_i
-        
-          style = "style=\"width: #{(100 / layout_columns).to_i - 1}%\""
-          
-          '<table class="kiss_field_columns"><tr>' +
-            (0...layout_columns).map do |i|
-              "<td #{style}>" + elements_html[i * num_elements_per_column, num_elements_per_column].join('<br/>') + "</td>"
-            end.join + '</table>'
-        else
-          elements_html.map {|h| "<nobr>#{h}</nobr>"}.join('&nbsp; ')
-        end
-      end
-      
       def param
-        @_param ||= @_form.params[@_name.to_s]
+        @_param ||= @_form.params[@_name]
       end
       
       def value
@@ -137,9 +104,10 @@ class Kiss
       end
       
       def value_string
-        v = value
+        return param if param
+        v = self.value
         v *= @_factor if v && @_factor
-        param || value_to_s(v)
+        value_to_s(v)
       end
       
       def add_error(message)
@@ -152,14 +120,10 @@ class Kiss
         value ? @_format.value_to_s(value, @_form.context) : ''
       end
       
-      def display_to_s(value)
-        value ? @_display_format.value_to_s(value).send(@_options_display_transform) : ''
-      end
-      
       def require_value(enter_verb = 'enter')
         if (param !~ /\S/)
           # value required
-          add_error("Please #{enter_verb} #{@_label}")
+          add_error("Please #{enter_verb} #{@_label.downcase}.")
           return
         end
       end
@@ -179,7 +143,14 @@ class Kiss
           p *= @_factor if @_factor
           value = p
         rescue Kiss::Format::ValidateError => e
-          return add_error("#{e.message.capitalize}")
+          return add_error("#{e.message.capitalize}.")
+        end
+        
+        if @_min_value_size && value.size < @_min_value_size
+          return add_error("#{name.capitalize} must be at least #{@_min_value_size} characters long.")
+        end
+        if @_max_value_size && value.size < @_max_value_size
+          return add_error("#{name.capitalize} must be no more than #{@_max_value_size} characters long.")
         end
         
         if @_match
@@ -190,7 +161,7 @@ class Kiss
         end
         
         if @_save && @_unique
-          dataset = @_object.model.filter(@_name.to_sym => value)
+          dataset = @_object.model.filter(@_key => value)
           unless (@_object.new? ? dataset : dataset.exclude(@_object.pk_hash)).empty?
             return add_error("There is already another #{@_object.model.name.singularize.gsub('_', ' ')} with the same #{@_label.downcase.gsub('_', ' ')}.")
           end
@@ -201,7 +172,7 @@ class Kiss
       
       def errors_html
         return nil unless @_errors.size > 0
-        
+                
         if @_errors.size == 1
           content = @_errors[0]
         else
@@ -220,7 +191,7 @@ class Kiss
           attrs[:style] ||= "width: #{width}px"
         end
         
-        @_currency.to_s + input_tag_html( attrs ) + tip_html(attrs)
+        @_currency.to_s + input_tag_html(attrs) + tip_html(attrs)
       end
       
       def table_row_html
@@ -233,7 +204,7 @@ class Kiss
       
       def html(*args)
         errors = errors_html
-        element_html(*args) + (errors ? (@_columns ? '' : '<br/>') + %Q(#{errors}) : '')
+        element_html(*args) + (errors ? ('<br/>' + errors) : '')
       end
       
       def tag_start_html(tag_name, attrs = {}, extra_html = nil)
@@ -275,12 +246,458 @@ class Kiss
       def input_tag_html(attrs = {}, extra_html = nil)
         tag_html(
           'input',
-          {:type => @_type}.merge(attrs),
+          {:type => self.class.type}.merge(attrs),
           extra_html
         )
       end
+      
+      def set_value_to_hash(h)
+        h[self.name] = self.value
+      end
+      
+      def set_value_to_object(obj)
+        k = self.key
+        v = (self.value != nil || obj.class.db_schema[k].allow_null) ?
+          self.value : (obj.class.db_schema[k][:default] ||= self.format.default)
+        
+        v = Digest.const_get(self.digest.to_sym).hexdigest(value) if self.digest
+        
+        obj[k] = v
+      end
+    end
+    
+    # Subclass for single-value field types that present and take their value
+    # from a set of options.
+    class MultiChoiceField < Field
+      dsl_accessor(
+        # (Enumerable) set of options to be presented for user choice
+        :options,
+        
+        # (Numeric or Symbol) This specifies which part of the option objects
+        # should be used as the field value to be submitted from this form.
+        # If each option is an enumerable, options_value_key should be a
+        # numeric index. If each option is a hash or model object, then this
+        # should be symbol key common to all of the option objects.
+        :options_value_key,
+        
+        # (Numeric or Symbol) This specifies which part of the option objects
+        # should be displayed to the user in the form's HTML representation.
+        # If each option is an enumerable, options_value_key should be a
+        # numeric index. If each option is a hash or model object, then this
+        # should be symbol key common to all of the option objects.
+        :options_display_key,
+        
+        # (Symbol) represents a Kiss::Format to be used in rendering each 
+        # option display object in the form output.
+        :display_format,
+        
+        # (Symbol) symbol of a method name to be called on each option display 
+        # object to get its text or HTML representation for the form output
+        # (after applying the display_format). Defaults to :to_s.
+        :options_display_transform,
+        
+        # (Numeric) Layout the options in a table grid with this many columns.
+        # If nil, layout the options on a single line with no grid.
+        :columns,
+        
+        # (Boolean) iff true, create and add a text field for the user to 
+        # specify a custom value for this field.
+        :other,
+        
+        # (Kiss::Form::Field) The field to be presented as the 'Other' field 
+        # for custom input from the user.
+        :other_field
+      )
+      alias_method :option_value_key, :options_value_key
+      alias_method :option_display_key, :options_display_key
+      alias_method :option_display_transform, :options_display_transform
+      
+      def initialize(*args, &block)
+        @_options_display_transform = :to_s
+        
+        super(*args, &block)
+        
+        @_display_format = Kiss::Format.lookup(@_display_format)
+        
+        if @_options
+          if @_options[0].is_a?(Array)
+            @_options_value_key ||= 0
+            (@_options_display_key ||= (@_options[0].size == 1) ? 0 : 1)
+          elsif defined?(Kiss::Model) && @_options[0].is_a?(Kiss::Model)
+            model_klass = @_options[0].class
+            @_options_value_key ||= model_klass.value_column
+            @_options_display_key ||= model_klass.display_column
+          elsif @_options[0].is_a?(Hash)
+            @_options_value_key ||= :id
+            @_options_display_key ||= :name
+          end
+        end
+        
+        if @_other
+          @_other_field = @_form.create_field( { :name => @_name + '.other' }.merge(@_other) )
+        end
+      end
+      
+      def form=(new_form)
+        super(new_form)
+        @_other_field.form = new_form if @_other_field
+      end
+      
+      def display_to_s(value)
+        value ? @_display_format.value_to_s(value).send(@_options_display_transform) : ''
+      end
+      
+      def options_keys(value, display)
+        @_options_value_key = value
+        @_options_display_key = display
+      end
+      alias_method :option_keys, :options_keys
+      
+      def option_pairs
+        pairs = if @_options_value_key
+          if @_options_display_key.is_a?(Proc)
+            @_options.map {|option| [ option[@_options_value_key], @_options_display_key.call(option) ]}
+          else
+            @_options.map {|option| [
+              option[@_options_value_key] || option.send(@_options_value_key), 
+              option[@_options_display_key] || option.send(@_options_display_key)
+            ]}
+          end
+        else
+          @_display_format = @_format
+          @_options.map {|option| [ option, option ]}
+        end
+        
+        pairs
+      end
+  
+      def has_option_value?(v)
+        !(@_options_value_key ?
+          @_options.select {|o| value_to_s(o[@_options_value_key]) == v } :
+          @_options.select {|o| value_to_s(o) == v }
+        ).empty?
+      end
+      
+      def column_layout(elements_html)
+        if elements_html.empty?
+          ''
+        elsif @_columns
+          layout_columns = [@_columns, elements_html.size].min
+          num_elements_per_column = ((elements_html.size + layout_columns - 1) / layout_columns).to_i
+          layout_columns = ((elements_html.size + num_elements_per_column - 1) / num_elements_per_column).to_i
+        
+          style = "style=\"width: #{(100 / layout_columns).to_i - 1}%\""
+          
+          '<table class="kiss_field_columns"><tr>' +
+            (0...layout_columns).map do |i|
+              "<td #{style}>" + elements_html[i * num_elements_per_column, num_elements_per_column].join('<br/>') + "</td>"
+            end.join + '</table>'
+        else
+          elements_html.map {|h| "<nobr>#{h}</nobr>"}.join('&nbsp; ')
+        end
+      end
+      
+      def validate
+        if @_other && param == 'other'
+          @_param = @_form.params[@_name+'.other']
+        end
+        super('select')
+        
+        if @_value =~ /\S/ && !has_option_value?(@_value)
+          add_error "Invalid selection" 
+        end
+      end
+      
+      def other_field_html
+        return '' unless @_other
+        
+        other_checked = @_value && !option_pairs.any? {|v, d| v == @_value }
+        
+        (@_columns ? '<br/>' : '&nbsp; ') + [
+          input_tag_html(
+            { :value => 'other', :html => { :id => @_name+'.other' } },
+            other_checked ? 'checked' : ''
+          ),
+          @_other[:label] || 'Other',
+          ': ',
+          @_currency.to_s,
+          input_tag_html({
+            :type => :text,
+            :name => @_name+'.other',
+            :value => other_checked ? value_to_s(@_value) : nil,
+            :html => {
+              :onfocus => "document.getElementById('#{@_name}.other').checked = true"
+            }
+          }.merge(@_other))
+        ].join
+      end
+    end
+    
+    # Subclass for field types in which multiple values can be chosen from a set
+    # of options.
+    class MultiValueField < MultiChoiceField
+      # (String) If not nil, then render a hidden form field specifying all of the
+      # values for this multi-value field, joined by this hidden_join delimiter.
+      # TODO: This may not be needed; remove if appropriate.
+      dsl_accessor :hidden_join
+      
+      def param
+        @_form.params[@_name + '[]'] || []
+      end
+      
+      def validate
+        begin
+          @_value = param.map { |p| @_format.validate(p) }
+        rescue Kiss::Format::ValidateError => e
+          return add_error("#{e.message.capitalize}.")
+        end
+        
+        if @_value.empty? && @_required
+          return add_error "Please select at least one #{@_label.downcase.singularize}."
+        end
+        
+        if @_min_value_size && @_value.size < @_min_value_size
+          return add_error "Please select at least #{@_min_value_size.of(@_label.downcase)}."
+        end
+        
+        if @_max_value_size && @_value.size > @_max_value_size
+          return add_error "Please select no more than #{@_max_value_size.of(@_label.downcase)}."
+        end
+        
+        @_value.each do |v|
+          unless has_option_value?(v)
+            return add_error "Invalid selection"
+          end
+        end
+      end
+  
+      def selected_option_values
+        @_selected_option_values ||= @_value ? Hash[ *(@_value.map {|v| [value_to_s(v), true]}.flatten) ] : {}
+      end
+    end
+    
+    ### Concrete Field Types ###
+    
+    class HiddenField < Field; end
+    class TextField < Field; end
+    
+    class TextAreaField < Field
+      dsl_accessor :rows, :cols
+      
+      def initialize(*args)
+        @_rows = 5
+        @_cols = 20
+        super(*args)
+      end
+      
+      def element_html(attrs = {})
+        content_tag_html(
+          'textarea',
+          value_string,
+          attrs.merge(
+            :rows => @_rows ||= 1,
+            :cols => @_cols ||= 1
+          )
+        ) + tip_html(attrs)
+      end
     end
-  end
-end
 
-require 'kiss/form/field_types'
+    class PasswordField < Field
+      def element_html(*args)
+        input_tag_html(*args)
+      end
+    end
+    
+    class FileField < Field
+      def element_html(attrs = {})
+        input_tag_html(attrs) + tip_html(attrs)
+      end
+      
+      def get_file_name; end
+  
+      def get_file_data; end
+      
+      def require_value(enter_verb)
+        p = param
+        return add_error("Please choose #{label.downcase}.") unless p && p[:type]
+      end
+      
+      def validate
+        require_value(nil) if @_required
+      end
+    end
+    
+    class RangeField < Field
+      dsl_accessor :min_field, :max_field
+      
+      def initialize(form, *args, &block)
+        super(form, *args, &block)
+        @_type = :range
+        
+        attrs = args.to_attrs
+        text_field_attrs = attrs.merge(
+          :style => 'width: 60px'
+        )
+        text_field_attrs[:html] ||= {}
+        
+        [:min, :max].each do |key|
+          text_field_name = "#{key}_#{attrs.name}"
+          text_field_attrs.merge!(
+            :name => text_field_name,
+            :key => text_field_name.to_sym
+          )
+          text_field_attrs[:html] = text_field_attrs[:html].clone
+          text_field_attrs[:html][:placeholder] = key
+          
+          instance_variable_set("@_#{key}_field".to_sym, 
+            TextField.new(form, text_field_attrs, &block))
+        end
+      end
+      
+      def validate
+        @_min_field.validate
+        @_max_field.validate
+        
+        (@_min_field.errors + @_max_field.errors).each do |error|
+          add_error(error)
+        end
+        nil
+      end
+      
+      def element_html
+        @_min_field.element_html + ' to ' + @_max_field.element_html
+      end
+      
+      def set_value_to_hash(h)
+        @_min_field.set_value_to_hash(h)
+        @_max_field.set_value_to_hash(h)
+      end
+      
+      def set_value_to_object(obj)
+        @_min_field.set_value_to_object(obj)
+        @_max_field.set_value_to_object(obj)
+      end
+    end
+    
+    class SubmitField < MultiChoiceField
+      dsl_accessor :cancel
+      
+      def initialize(*args)
+        @_save = false
+        super(*args)
+      end
+      
+      def element_html(*args)
+        elements_html(*args).join(' ')
+      end
+      
+      def elements_html(attrs = {})
+        @_options.map do |option|
+          input_tag_html(attrs.merge( :value => value_to_s(option) ))
+        end
+      end
+    end
+
+    class SelectField < MultiChoiceField
+      dsl_accessor :choose_here
+      
+      def element_html(attrs = {})
+        return 'No options' unless @_options.size > 0
+        
+        @_choose_here ||= 'Choose Here'
+        placeholder_html = %Q(<option value="">#{@_choose_here}</option>)
+        
+        options_html = option_pairs.map do |option_value, option_display|
+          option_value_string = value_to_s(option_value)
+          selected = (value_string == option_value_string) ? ' selected' : ''
+          %Q(<option value="#{option_value_string}"#{selected}>#{display_to_s(option_display)}</option>)
+        end.join
+        
+        content_tag_html('select', placeholder_html + options_html, attrs) + other_field_html + tip_html(attrs)
+      end
+    end
+
+    class RadioField < MultiChoiceField
+      def element_html(attrs = {})
+        column_layout(elements_html(attrs)) + other_field_html + tip_html(attrs)
+      end
+      
+      def elements_html(attrs = {})
+        option_pairs.map do |option_value, option_display|
+          option_value_string = value_to_s(option_value)
+          input_tag_html(
+            attrs.merge( :type => 'radio', :value => option_value_string ),
+            (value_string == option_value_string) ? 'checked' : ''
+          ) + @_currency.to_s + display_to_s(option_display)
+        end
+      end
+    end
+
+    class BooleanField < RadioField
+      def initialize(*args, &block)
+        @_options = [[1, 'Yes'], [0, 'No']]
+        super(*args, &block)
+      end
+    end
+
+    class CheckboxField < MultiValueField
+      def element_html(attrs = {})
+        hidden_options = @_hidden_join ? input_tag_html(
+          :type => 'hidden',
+          :name => "#{@_name}_options",
+          :value => option_pairs.map {|option_value, option_display| value_to_s(option_value) }.join(@_hidden_join)
+        ) : ''
+        
+        column_layout(elements_html(attrs)) + other_field_html + hidden_options + tip_html(attrs)
+      end
+      
+      def elements_html(attrs = {})
+        name = @_name + '[]'
+        option_pairs.map do |option_value, option_display|
+          option_value_string = value_to_s(option_value)
+          
+          input_tag_html(
+            attrs.merge( :name => name, :value => option_value_string ),
+            selected_option_values[option_value_string] ? 'checked' : ''
+          ) + @_currency.to_s + display_to_s(option_display)
+        end
+      end
+    end
+
+    class MultiSelectField < MultiValueField
+      def element_html(attrs = {})
+        options_html = option_pairs.map do |option_value, option_display|
+          option_value_string = value_to_s(option_value)
+          selected = selected_option_values[option_value_string] ? ' selected' : ''
+          %Q(<option value="#{option_value_string}"#{selected}>#{display_to_s(option_display)}</option>)
+        end.join
+        
+        content_tag_html(
+          'select',
+          options_html,
+          attrs,
+          'multiple'
+        )
+      end
+    end
+    
+    # Component type symbols used to create form definition DSL
+    COMPONENT_TYPES = {
+      :text => TextField,
+      :hidden => HiddenField,
+      :textarea => TextAreaField,
+      :password => PasswordField,
+      :boolean => BooleanField,
+      :range => RangeField,
+      :file => FileField,
+      :select => SelectField,
+      :radio => RadioField,
+      :checkbox => CheckboxField,
+      :multiselect => MultiSelectField,
+      :submit => SubmitField
+    }
+    COMPONENT_TYPES.each_pair do |type, klass|
+      klass.type = type
+    end
+  end
+end