bureaucrat 0.0.3 → 0.10.0

data/lib/bureaucrat/forms.rb

@@ -1,199 +1,284 @@
-require 'bureaucrat/utils'
-require 'bureaucrat/validation'
-require 'bureaucrat/widgets'
-require 'bureaucrat/fields'
-
-module Bureaucrat; module Forms
-  class BoundField
-    include Utils
-
-    attr_accessor :label
-
-    def initialize(form, field, name)
-      @form = form
-      @field = field
-      @name = name
-      @html_name = form.add_prefix(name).to_sym
-      @html_initial_name = form.add_initial_prefix(name).to_sym
-      @label = @field.label || pretty_name(name)
-      @help_text = @field.help_text || ''
-    end
+module Bureaucrat
+  module Forms
+
+    # Instances of +BoundField+ represent a fields with associated data.
+    # +BoundField+s are used internally by the +Form+ class.
+    class BoundField
+      include Utils
+
+      # Field label text
+      attr_accessor :label, :form, :field, :name, :html_name, :html_initial_name, :help_text
+
+      # Instantiates a new +BoundField+ associated to +form+'s field +field+
+      # named +name+.
+      def initialize(form, field, name)
+        @form = form
+        @field = field
+        @name = name
+        @html_name = form.add_prefix(name)
+        @html_initial_name = form.add_initial_prefix(name)
+        @label = @field.label || pretty_name(name)
+        @help_text = @field.help_text || ''
+      end
 
-    def to_s
-      @field.show_hidden_initial ? as_widget + as_hidden(nil, true) : as_widget
-    end
+      # Renders the field.
+      def to_s
+        @field.show_hidden_initial ? as_widget + as_hidden(nil, true) : as_widget
+      end
 
-    def errors
-      @form.errors.fetch(@name, @form.error_class.new)
-    end
+      # Errors for this field.
+      def errors
+        @form.errors.fetch(@name, @form.error_class.new)
+      end
+
+      # Renders this field with the option of using alternate widgets
+      # and attributes.
+      def as_widget(widget=nil, attrs=nil, only_initial=false)
+        widget ||= @field.widget
+        attrs ||= {}
+        auto_id = self.auto_id
+        attrs[:id] ||= auto_id if auto_id && !widget.attrs.key?(:id)
 
-    def as_widget(widget=nil, attrs=nil, only_initial=false)
-      widget ||= @field.widget
-      attrs ||= {}
-      auto_id = self.auto_id
-      attrs[:id] ||= auto_id if auto_id && !widget.attrs.key?(:id)
-
-      if !@form.bound?
-        data = @form.initial.fetch(@name.to_s, @field.initial)
-        data = data.call if data.respond_to?(:call)
-      else
-        if @field.is_a?(Fields::FileField) && @data.nil?
+        if !@form.bound?
           data = @form.initial.fetch(@name, @field.initial)
+          data = data.call if data.respond_to?(:call)
         else
-          data = self.data
+          if @field.is_a?(Fields::FileField) && @data.nil?
+            data = @form.initial.fetch(@name, @field.initial)
+          else
+            data = self.data
+          end
         end
+
+        name = only_initial ? @html_initial_name : @html_name
+        widget.render(name.to_s, data, attrs)
       end
 
-      name = only_initial ? @html_initial_name : @html_name
+      # Renders this field as a text input.
+      def as_text(attrs=nil, only_initial=false)
+        as_widget(Widgets::TextInput.new, attrs, only_initial)
+      end
 
-      widget.render(name.to_s, data, attrs)
-    end
+      # Renders this field as a text area.
+      def as_textarea(attrs=nil, only_initial=false)
+        as_widget(Widgets::Textarea.new, attrs, only_initial)
+      end
 
-    def as_text(attrs=nil, only_initial=false)
-      as_widget(Widgets::TextInput.new, attrs, only_initial)
-    end
+      # Renders this field as hidden.
+      def as_hidden(attrs=nil, only_initial=false)
+        as_widget(@field.hidden_widget, attrs, only_initial)
+      end
 
-    def as_textarea(attrs=nil, only_initial=false)
-      as_widget(Widgets::Textarea.new, attrs, only_initial)
-    end
+      # The data associated to this field.
+      def data
+        @field.widget.value_from_formdata(@form.data, @html_name)
+      end
 
-    def as_hidden(attrs=nil, only_initial=false)
-      as_widget(@field.hidden_widget, attrs, only_initial)
-    end
+      def value
+        # Returns the value for this BoundField, using the initial value if
+        # the form is not bound or the data otherwise.
 
-    def data
-      @field.widget.value_from_datahash(@form.data, @form.files, @html_name)
-    end
+        if form.bound?
+          val = field.bound_data(data, form.initial.fetch(name, field.initial))
+        else
+          val = form.initial.fetch(name, field.initial)
+          if val.respond_to?(:call)
+            val = val.call
+          end
+        end
+
+        field.prepare_value(val)
+      end
+
+      # Renders the label tag for this field.
+      def label_tag(contents=nil, attrs=nil)
+        contents ||= conditional_escape(@label)
+        widget = @field.widget
+        id_ = widget.attrs[:id] || self.auto_id
 
-    def label_tag(contents=nil, attrs=nil)
-      contents ||= conditional_escape(@label)
-      widget = @field.widget
-      id_ = widget.attrs[:id] || self.auto_id
+        if id_
+          attrs = attrs ? flatatt(attrs) : ''
+          contents = "<label for=\"#{Widgets::Widget.id_for_label(id_)}\"#{attrs}>#{contents}</label>"
+        end
 
-      if id_
-        attrs = attrs ? flattatt(attrs) : ''
-        contents = "<label for=\"#{Widgets::Widget.id_for_label(id_)}\"#{attrs}>#{contents}</label>"
+        mark_safe(contents)
       end
 
-      mark_safe(contents)
-    end
+      def css_classes(extra_classes = nil)
+        # Returns a string of space-separated CSS classes for this field.
 
-    def hidden?
-      @field.widget.hidden?
-    end
+        if extra_classes.respond_to?(:split)
+          extra_classes = extra_classes.split
+        end
 
-    def auto_id
-      fauto_id = @form.auto_id
-      fauto_id ? fauto_id % @html_name : ''
-    end
-  end
+        extra_classes = Set.new(extra_classes)
 
-  class Form
-    include Utils
-    include Validation
+        if !errors.empty? && !Utils.blank_value?(form.error_css_class)
+          extra_classes << form.error_css_class
+        end
 
-    class << self
-      attr_writer :base_fields
+        if field.required && !Utils.blank_value?(form.required_css_class)
+          extra_classes << form.required_css_class
+        end
 
-      def base_fields
-        @base_fields ||= Utils::OrderedHash.new
+        extra_classes.to_a.join(' ')
       end
 
-      def field(name, field_obj)
-        base_fields[name] = field_obj
+      # true if the widget for this field is of the hidden kind.
+      def hidden?
+        @field.widget.hidden?
       end
 
-      # Copy data to the child class
-      def inherited(c)
-        super(c)
-        c.base_fields = base_fields.dup
+      # Generates the id for this field.
+      def auto_id
+        fauto_id = @form.auto_id
+        fauto_id ? fauto_id % @html_name : ''
       end
     end
 
-    attr_accessor :error_class, :auto_id, :initial, :data, :files, :cleaned_data
-
-    def bound? ; @is_bound; end
-
-    def initialize(data=nil, options={})
-      @is_bound = !data.nil?
-      @data = {}
-      data.each {|k, v| @data[k.to_sym] = @data[k] = v} if data
-      @files = options.fetch(:files, {})
-      @auto_id = options.fetch(:auto_id, 'id_%s')
-      @prefix = options[:prefix]
-      @initial = options.fetch(:initial, {})
-      @error_class = options.fetch(:error_class, Fields::ErrorList)
-      @label_suffix = options.fetch(:label_suffix, ':')
-      @empty_permitted = options.fetch(:empty_permitted, false)
-      @errors = nil
-      @changed_data = nil
-
-      @fields = self.class.base_fields.dup
-      @fields.each { |key, value| @fields[key] = value.dup }
-    end
+    # Base class for forms. Forms are a collection of fields with data that
+    # knows how to render and validate itself.
+    #
+    # === Bound vs Unbound forms
+    # A form is 'bound' if it was initialized with a set of data for its fields,
+    # otherwise it is 'unbound'. Only bound forms can be validated. Unbound
+    # forms always respond with false to +valid?+ and return an empty
+    # list of errors.
 
-    def to_s
-      as_table
-    end
+    class Form
+      include Utils
 
-    def [](name)
-      field = @fields[name] or return nil
-      BoundField.new(self, field, name)
-    end
+      # Fields associated to the form class
+      def self.base_fields
+        @base_fields ||= {}
+      end
 
-    def errors
-      full_clean if @errors.nil?
-      @errors
-    end
+      # Declares a named field to be used on this form.
+      def self.field(name, field_obj)
+        base_fields[name] = field_obj
+      end
 
-    def valid?
-      @is_bound && (errors.nil? || errors.empty?)
-    end
+      # Copy data to the child class
+      def self.inherited(c)
+        super(c)
+        c.instance_variable_set(:@base_fields, base_fields.dup)
+      end
 
-    def add_prefix(field_name)
-      @prefix ? :"#{@prefix}-#{field_name}" : field_name
-    end
+      # Error object class for this form
+      attr_accessor :error_class
+      # Required class for this form
+      attr_accessor :required_css_class
+      # Required class for this form
+      attr_accessor :error_css_class
+      # Format string for field id generator
+      attr_accessor :auto_id
+      # Hash of {field_name => initial_value}
+      attr_accessor :initial
+      # Data associated to this form {field_name => value}
+      attr_accessor :data
+      # TODO: complete implementation
+      attr_accessor :files
+      # Validated and cleaned data
+      attr_accessor :cleaned_data
+      # Fields belonging to this form
+      attr_accessor :fields
+
+      # Checks if this form was initialized with data.
+      def bound? ; @is_bound; end
+
+      # Instantiates a new form bound to the passed data (or unbound if data is nil)
+      #
+      # +data+ is a hash of {field_name => value} for this form to be bound
+      # (will be unbound if nil)
+      #
+      # Possible options are:
+      #   :prefix          prefix that will be used for fields when rendered
+      #   :auto_id         format string that will be used when generating
+      #                    field ids (default: 'id_%s')
+      #   :initial         hash of {field_name => default_value}
+      #                    (doesn't make a form bound)
+      #   :error_class     class used to represent errors (default: ErrorList)
+      #   :label_suffix    suffix string that will be appended to labels' text
+      #                    (default: ':')
+      #   :empty_permitted boolean value that specifies if this form is valid
+      #                    when empty
+
+      def initialize(data=nil, options={})
+        @is_bound = !data.nil?
+        @data = StringAccessHash.new(data || {})
+        @files = options.fetch(:files, {})
+        @auto_id = options.fetch(:auto_id, 'id_%s')
+        @prefix = options[:prefix]
+        @initial = StringAccessHash.new(options.fetch(:initial, {}))
+        @error_class = options.fetch(:error_class, Fields::ErrorList)
+        @label_suffix = options.fetch(:label_suffix, ':')
+        @empty_permitted = options.fetch(:empty_permitted, false)
+        @errors = nil
+        @changed_data = nil
+
+        @fields = self.class.base_fields.dup
+        @fields.each { |key, value| @fields[key] = value.dup }
+      end
 
-    def add_initial_prefix(field_name)
-      "initial-#{add_prefix(field_name)}"
-    end
+      # Iterates over the fields
+      def each
+        @fields.each do |name, field|
+          yield BoundField.new(self, field, name)
+        end
+      end
 
-    def empty_permitted?
-      @empty_permitted
-    end
+      # Access a named field
+      def [](name)
+        field = @fields[name] or return nil
+        BoundField.new(self, field, name)
+      end
 
-    def as_table
-      html_output('<tr><th>%(label)s</th><td>%(errors)s%(field)s%(help_text)s</td></tr>',
-                  '<tr><td colspan="2">%s</td></tr>', '</td></tr>',
-                  '<br />%s', false)
-    end
+      # Errors for this forms (runs validations)
+      def errors
+        full_clean if @errors.nil?
+        @errors
+      end
 
-    def as_ul
-      html_output('<li>%(errors)s%(label)s %(field)s%(help_text)s</li>',
-                  '<li>%s</li>', '</li>', ' %s', false)
-    end
+      # Perform validation and returns true if there are no errors
+      def valid?
+        @is_bound && (errors.nil? || errors.empty?)
+      end
 
-    def as_p
-      html_output('<p>%(label)s %(field)s%(help_text)s</p>',
-                  '%s', '</p>', ' %s', true)
-    end
+      # Generates a prefix for field named +field_name+
+      def add_prefix(field_name)
+        @prefix ? "#{@prefix}-#{field_name}" : field_name
+      end
 
-    def non_field_errors
-      errors.fetch(:__NON_FIELD_ERRORS, @error_class.new)
-    end
+      # Generates an initial-prefix for field named +field_name+
+      def add_initial_prefix(field_name)
+        "initial-#{add_prefix(field_name)}"
+      end
+
+      # true if the form is valid when empty
+      def empty_permitted?
+        @empty_permitted
+      end
 
-    def full_clean
-      @errors = Fields::ErrorHash.new
+      # Returns the list of errors that aren't associated to a specific field
+      def non_field_errors
+        errors.fetch(:__NON_FIELD_ERRORS, @error_class.new)
+      end
+
+      # Runs all the validations for this form. If the form is invalid
+      # the list of errors is populated, if it is valid, cleaned_data is
+      # populated
+      def full_clean
+        @errors = Fields::ErrorHash.new
 
-      return unless bound?
+        return unless bound?
 
-      @cleaned_data = {}
+        @cleaned_data = StringAccessHash.new
 
-      return if empty_permitted? && !changed?
+        return if empty_permitted? && !changed?
 
-      @fields.each do |name, field|
-          value = field.widget.value_from_datahash(@data, @files,
-                                                   add_prefix(name))
+        @fields.each do |name, field|
+          value = field.widget.
+            value_from_formdata(@data, add_prefix(name))
 
           begin
             if field.is_a?(Fields::FileField)
@@ -205,142 +290,96 @@ module Bureaucrat; module Forms
 
             clean_method = 'clean_%s' % name
             @cleaned_data[name] = send(clean_method) if respond_to?(clean_method)
-          rescue Fields::FieldValidationError => e
+          rescue ValidationError => e
             @errors[name] = e.messages
-            @cleaned_data.clear
+            @cleaned_data.delete(name)
           end
         end
 
-      begin
-        @cleaned_data = clean
-      rescue Fields::FieldValidationError => e
-        @errors[:__NON_FIELD_ERRORS] = e.messages
+        begin
+          @cleaned_data = clean
+        rescue ValidationError => e
+          @errors[:__NON_FIELD_ERRORS] = e.messages
+        end
+        @cleaned_data = nil if @errors && !@errors.empty?
       end
-      @cleaned_data = nil if @errors && !@errors.empty?
-    end
 
-    def clean
-      @cleaned_data
-    end
+      # Performs the last step of validations on the form, override in subclasses
+      # to customize behaviour.
+      def clean
+        @cleaned_data
+      end
 
-    def changed?
-      changed_data && !changed_data.empty?
-    end
+      # true if the form has data that isn't equal to its initial data
+      def changed?
+        changed_data && !changed_data.empty?
+      end
 
-    def changed_data
-      if @changed_data.nil?
-        @changed_data = []
+      # List names for fields that have changed data
+      def changed_data
+        if @changed_data.nil?
+          @changed_data = []
 
-        @fields.each do |name, field|
+          @fields.each do |name, field|
             prefixed_name = add_prefix(name)
-            data_value = field.widget.value_from_datahash(@data, @files,
-                                                          prefixed_name)
+            data_value = field.widget.
+              value_from_formdata(@data, prefixed_name)
+
             if !field.show_hidden_initial
               initial_value = @initial.fetch(name, field.initial)
             else
               initial_prefixed_name = add_initial_prefix(name)
               hidden_widget = field.hidden_widget.new
-              initial_value = hidden_widget.value_from_datahash(@data, @files,
-                                                                initial_prefixed_name)
+              initial_value = hidden_widget.
+                value_from_formdata(@data, initial_prefixed_name)
             end
 
             @changed_data << name if
               field.widget.has_changed?(initial_value, data_value)
           end
-      end
-
-      @changed_data
-    end
-
-    def media
-      @fields.values.inject(Widgets::Media.new) do |media, field|
-          media + field.widget.media
         end
-    end
-
-    def multipart?
-      @fields.any? {|f| f.widgetneeds_multipart_form?}
-    end
-
-    def hidden_fields
-      @fields.select {|f| f.hidden?}
-    end
 
-    def visible_fields
-      @fields.select {|f| !f.hidden?}
-    end
+        @changed_data
+      end
 
-  private
-    def html_output(normal_row, error_row, row_ender, help_text_html,
-                    errors_on_separate_row)
-      top_errors = non_field_errors
-      output, hidden_fields = [], []
+      # true if this form contains fields that require the form to be
+      # multipart
+      def multipart?
+        @fields.any? {|f| f.widget.multipart_form?}
+      end
 
-      add_fields_output(output, hidden_fields, normal_row, error_row,
-                        help_text_html, errors_on_separate_row, top_errors)
-      output = [error_row % top_errors] + output unless top_errors.empty?
-      add_hidden_fields_output(output, hidden_fields, row_ender)
+      # List of hidden fields.
+      def hidden_fields
+        @fields.select {|f| f.hidden?}
+      end
 
-      mark_safe(output.join("\n"))
-    end
+      # List of visible fields
+      def visible_fields
+        @fields.select {|f| !f.hidden?}
+      end
 
-    def add_fields_output(output, hidden_fields, normal_row, error_row,
-                          help_text_html, errors_on_separate_row,
-                          top_errors)
-      @fields.each do |name, field|
-          bf = BoundField.new(self, field, name)
-          bf_errors = @error_class.new(bf.errors.map {|e| conditional_escape(e)})
-          if bf.hidden?
-            top_errors += bf_errors.map do |e|
-              "(Hidden field #{name}) #{e.to_s}"
-            end unless bf_errors.empty?
-            hidden_fields << bf.to_s
-          else
-            output << error_row % bf_errors if
-              errors_on_separate_row && !bf_errors.empty?
-
-            label = ''
-            unless bf.label.nil? || bf.label.empty?
-              label = conditional_escape(bf.label)
-              label += @label_suffix if @label_suffix && label[-1,1] !~ /[:?.!]/
-              label = bf.label_tag(label)
-            end
+      # Attributes for labels, override in subclasses to customize behaviour
+      def label_attributes(name, field)
+        {}
+      end
 
-            help_text = field.help_text.empty? ? '' : help_text_html % field.help_text
-            vars = {
-              :errors => bf_errors, :label => label,
-              :field => bf, :help_text => help_text
-            }
-            output << format_string(normal_row, vars)
-          end
+      # Populates the passed object's attributes with data from the fields
+      def populate_object(object)
+        @fields.each do |name, field|
+          field.populate_object(object, name, @cleaned_data[name])
         end
-    end
+      end
 
-    def add_hidden_fields_output(output, hidden_fields, row_ender)
-      unless hidden_fields.empty?
-        str_hidden = hidden_fields.join('')
-
-        unless output.empty?
-          last_row = output[-1]
-          if last_row !~ /#{row_ender}$/
-            vars = {
-              :errors => '', :label => '', :field => '', :help_text => ''
-            }
-            last_row = format_string(normal_row, vars)
-            output << last_row
-          end
-          output[-1] = last_row[0...-row_ender.length] + str_hidden + row_ender
-        else
-          output << str_hidden
-        end
+    private
+
+      # Returns the value for the field name +field_name+ from the associated
+      # data
+      def raw_value(fieldname)
+        field = @fields.fetch(fieldname)
+        prefix = add_prefix(fieldname)
+        field.widget.value_from_formdata(@data, prefix)
       end
-    end
 
-    def raw_value(fieldname)
-      field = @fields.fetch(fieldname)
-      prefix = add_prefix(fieldname)
-      field.widget.value_from_datahash(@data, @files, prefix)
     end
-
   end
-end; end
+end