formtastic 1.2.5 → 2.0.0.rc1

data/lib/formtastic/engine.rb

@@ -0,0 +1,7 @@
+# Configure Rails 3.1 to have assert_select_jquery() in tests
+module Formtastic
+  # Required for formtastic.css to be discoverable in the asset pipeline
+  # @private
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/formtastic/form_builder.rb

@@ -0,0 +1,83 @@
+module Formtastic
+  class FormBuilder < ActionView::Helpers::FormBuilder
+
+    def self.configure(name, value = nil)
+      class_attribute(name)
+      self.send(:"#{name}=", value)
+    end
+
+    configure :custom_namespace
+    configure :default_text_field_size
+    configure :default_text_area_height, 20
+    configure :default_text_area_width
+    configure :all_fields_required_by_default, true
+    configure :include_blank_for_select_by_default, true
+    configure :required_string, proc { Formtastic::Util.html_safe(%{<abbr title="#{Formtastic::I18n.t(:required)}">*</abbr>}) }
+    configure :optional_string, ''
+    configure :inline_errors, :sentence
+    configure :label_str_method, :humanize
+    configure :collection_label_methods, %w[to_label display_name full_name name title username login value to_s]
+    configure :collection_value_methods, %w[id to_s]
+    configure :custom_inline_order, {}
+    configure :file_methods, [ :file?, :public_filename, :filename ]
+    configure :file_metadata_suffixes, ['content_type', 'file_name', 'file_size']
+    configure :priority_countries, ["Australia", "Canada", "United Kingdom", "United States"]
+    configure :i18n_lookups_by_default, true
+    configure :escape_html_entities_in_hints_and_labels, true
+    configure :default_commit_button_accesskey
+    configure :default_inline_error_class, 'inline-errors'
+    configure :default_error_list_class, 'errors'
+    configure :default_hint_class, 'inline-hints'
+
+    attr_reader :template
+
+    attr_reader :auto_index
+
+    include Formtastic::HtmlAttributes
+
+    include Formtastic::Helpers::InputHelper
+    include Formtastic::Helpers::InputsHelper
+    include Formtastic::Helpers::ButtonsHelper
+    include Formtastic::Helpers::ErrorsHelper
+    
+    # This is a wrapper around Rails' `ActionView::Helpers::FormBuilder#fields_for`, originally 
+    # provided to ensure that the `:builder` from `semantic_form_for` was passed down into
+    # the nested `fields_for`. Rails 3 no longer requires us to do this, so this method is
+    # provided purely for backwards compatibility and DSL consistency.
+    #
+    # When constructing a `fields_for` form fragment *outside* of `semantic_form_for`, please use
+    # `Formtastic::Helpers::FormHelper#semantic_fields_for`.
+    #
+    # @see http://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html#method-i-fields_for ActionView::Helpers::FormBuilder#fields_for
+    # @see http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-fields_for ActionView::Helpers::FormHelper#fields_for
+    # @see Formtastic::Helpers::FormHelper#semantic_fields_for
+    #
+    # @example
+    #   <% semantic_form_for @post do |post| %>
+    #     <% post.semantic_fields_for :author do |author| %>
+    #       <% author.inputs :name %>
+    #     <% end %>
+    #   <% end %>
+    #
+    #   <form ...>
+    #     <fieldset class="inputs">
+    #       <ol>
+    #         <li class="string"><input type='text' name='post[author][name]' id='post_author_name' /></li>
+    #       </ol>
+    #     </fieldset>
+    #   </form>
+    #
+    # @todo is there a way to test the params structure of the Rails helper we wrap to ensure forward compatibility?
+    def semantic_fields_for(record_or_name_or_array, *args, &block)
+      # Add a :parent_builder to the args so that nested translations can be possible in Rails 3
+      options = args.extract_options!
+      options[:parent_builder] ||= self
+      
+      # Wrap the Rails helper
+      fields_for(record_or_name_or_array, *(args << options), &block)
+    end
+    
+  end
+
+end
+

data/lib/formtastic/helpers.rb

@@ -0,0 +1,16 @@
+module Formtastic
+  # @private
+  module Helpers
+    autoload :ButtonsHelper, 'formtastic/helpers/buttons_helper'
+    autoload :ErrorsHelper, 'formtastic/helpers/errors_helper'
+    autoload :FieldsetWrapper, 'formtastic/helpers/fieldset_wrapper'
+    autoload :FileColumnDetection, 'formtastic/helpers/file_column_detection'
+    autoload :FormHelper, 'formtastic/helpers/form_helper'
+    autoload :InputHelper, 'formtastic/helpers/input_helper'
+    autoload :InputsHelper, 'formtastic/helpers/inputs_helper'
+    autoload :LabelHelper, 'formtastic/helpers/label_helper'
+    autoload :SemanticFormHelper, 'formtastic/helpers/semantic_form_helper'
+    autoload :Reflection, 'formtastic/helpers/reflection'
+  end
+end
+

data/lib/formtastic/helpers/buttons_helper.rb

@@ -0,0 +1,277 @@
+module Formtastic
+  module Helpers
+
+    # ButtonsHelper encapsulates the responsibilties of the {#buttons} and {#commit_button} helpers
+    # for submitting forms.
+    #
+    # {#buttons} is used to wrap the form's button(s) and actions in a `<fieldset>` and `<ol>`,
+    # with each item in the list containing the markup representing a single button.
+    #
+    # {#buttons} is usually called with a block containing a single {#commit_button} call:
+    #
+    #     <%= semantic_form_for @post do |f| %>
+    #       ...
+    #       <%= f.buttons do %>
+    #         <%= f.commit_button
+    #       <% end %>
+    #     <% end %>
+    #
+    # The HTML output will be something like:
+    #
+    #     <form class="formtastic" method="post" action="...">
+    #       ...
+    #       <fieldset class="buttons">
+    #         <ol>
+    #           <li class="commit">
+    #             <input type="submit" name="commit" value="Create Post" class="create">
+    #           </li>
+    #         </ol>
+    #       </fieldset>
+    #     </form>
+    #
+    # While this may seem slightly over-engineered, it is consistent with the way form inputs are
+    # handled, and makes room for other types of buttons and actions in future versions (such as
+    # cancel buttons or links, reset buttons and even alternate actions like 'save and continue
+    # editing').
+    #
+    # It's important to note that the `semantic_form_for` and {#buttons} blocks wrap the
+    # standard Rails `form_for` helper and form builder, so you have full access to every standard
+    # Rails form helper, with any HTML markup and ERB syntax, allowing you to "break free" from
+    # Formtastic when it doesn't suit to create your own buttons, links and actions:
+    #
+    #     <%= semantic_form_for @post do |f| %>
+    #       ...
+    #       <%= f.buttons do %>
+    #         <li class="save">
+    #           <%= f.submit "Save" %>
+    #         <li>
+    #         <li class="cancel-link">
+    #           Or <%= link_to "Cancel", posts_url %>
+    #         <li>
+    #       <% end %>
+    #     <% end %>
+    #
+    # There are many other syntax variations and arguments to customize your form. See the
+    # full documentation of {#buttons} and {#commit_button} for details.
+    module ButtonsHelper
+      include Formtastic::Helpers::FieldsetWrapper
+      include Formtastic::LocalizedString
+
+      # Creates a fieldset and ol tag wrapping for use around a set of buttons. It can be
+      # called either with a block (in which you can do the usual Rails form stuff, HTML, ERB, etc),
+      # or with a list of named buttons. These two examples are functionally equivalent:
+      #
+      #     # With a block:
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <% f.buttons do %>
+      #         <%= f.commit_button %>
+      #       <% end %>
+      #     <% end %>
+      #
+      #     # With a list of fields:
+      #     <% semantic_form_for @post do |f| %>
+      #       <%= f.buttons :commit %>
+      #     <% end %>
+      #
+      #     # Output:
+      #     <form ...>
+      #       <fieldset class="inputs">
+      #         <ol>
+      #           <li class="commit">
+      #             <input type="submit" ...>
+      #           </li>
+      #         </ol>
+      #       </fieldset>
+      #     </form>
+      #
+      # Only one type of named button is supported at this time (:commit), and it's assumed to be
+      # the default choice, so this is also functionally equivalent, but may change in the future:
+      #
+      #     # With no args:
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <%= f.buttons %>
+      #     <% end %>
+      #
+      # While this may seem slightly over-engineered, it is consistent with the way form inputs are
+      # handled, and makes room for other types of buttons and actions in future versions (such as
+      # cancel buttons or links, reset buttons and even alternate actions like 'save and continue
+      # editing').
+      #
+      # All options except `:name` and `:title` are passed down to the fieldset as HTML
+      # attributes (`id`, `class`, `style`...). If provided, the `:name` or `:title` option is
+      # passed into a `<legend>` inside the `<fieldset>` to name the set of buttons.
+      #
+      # @example Quickly add button(s) to the form, accepting all default values, options and behaviors
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <%= f.buttons %>
+      #     <% end %>
+      #
+      # @example Specify which named buttons you want, accepting all default values, options and behaviors
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <%= f.buttons :commit %>
+      #     <% end %>
+      #
+      # @example Specify which named buttons you want, and name the fieldset
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <%= f.buttons :commit, :name => "Actions" %>
+      #       or
+      #       <%= f.buttons :commit, :label => "Actions" %>
+      #     <% end %>
+      #
+      # @example Get full control over the commit_button options
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <%= f.buttons do %>
+      #         <%= f.commit_button :label => "Go", :button_html => { :class => "pretty" :disable_with => "Wait..." }, :wrapper_html => { ... }
+      #       <% end %>
+      #     <% end %>
+      #
+      # @example Make your own custom buttons, links or actions with standard Rails helpers or HTML
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <%= f.buttons do %>
+      #         <li class="submit">
+      #           <%= f.submit "Submit" %>
+      #         </li>
+      #         <li class="reset">
+      #           <input type="reset" value="Reset">
+      #         </li>
+      #         <li class="cancel">
+      #           <%= link_to "Cancel", posts_url %>
+      #         </li>
+      #       <% end %>
+      #     <% end %>
+      #
+      # @example Add HTML attributes to the fieldset
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <%= f.buttons :commit, :style => "border:1px;" %>
+      #       or
+      #       <%= f.buttons :style => "border:1px;" do %>
+      #         ...
+      #       <% end %>
+      #     <% end %>
+      #
+      # @option *args :label [String, Symbol]
+      #   Optionally specify text for the legend of the fieldset
+      #
+      # @option *args :name [String, Symbol]
+      #   Optionally specify text for the legend of the fieldset (alias for `:label`)
+      #
+      # @todo document i18n keys
+      def buttons(*args, &block)
+        html_options = args.extract_options!
+        html_options[:class] ||= "buttons"
+
+        if block_given?
+          field_set_and_list_wrapping(html_options, &block)
+        else
+          args = [:commit] if args.empty?
+          contents = args.map { |button_name| send(:"#{button_name}_button") }
+          field_set_and_list_wrapping(html_options, contents)
+        end
+      end
+
+      # Creates a submit input tag with the value "Save [model name]" (for existing records) or
+      # "Create [model name]" (for new records) by default. The output is an `<input>` tag with the
+      # `type` of `submit` and a class of either `create` or `update` (if Formtastic can determin if)
+      # the record is new or not) with `submit` as a fallback class. The submit button is wrapped in
+      # an `<li>` tag with a class of `commit`, and is intended to be rendered inside a {#buttons}
+      # block which wraps the button in a `fieldset` and `ol`.
+      #
+      # The textual value of the label can be changed from this default through the `:label`
+      # argument or through i18n.
+      #
+      # You can pass HTML attributes down to the `<input>` tag with the `:button_html` option, and
+      # pass HTML attributes to the wrapping `<li>` tag with the `:wrapper_html` option.
+      #
+      # @example Basic usage
+      #   # form
+      #   <%= semantic_form_for @post do |f| %>
+      #     ...
+      #     <%= f.buttons do %>
+      #       <%= f.commit_button %>
+      #     <% end %>
+      #   <% end %>
+      #
+      #   # output
+      #   <form ...>
+      #     ...
+      #     <fieldset class="buttons">
+      #       <input name="commit" type="submit" value="Create Post" class="create">
+      #     </fieldset>
+      #   </form>
+      #
+      # @example Set the value through the `:label` option
+      #   <%= f.commit_button :label => "Go" %>
+      #
+      # @example Set the value through the optional first argument (like Rails' `f.submit`)
+      #   <%= f.commit_button "Go" %>
+      #
+      # @example Pass HTML attributes down to the `<input>`
+      #   <%= f.commit_button :button_html => { :class => 'pretty', :accesskey => 'g', :disable_with => "Wait..." } %>
+      #   <%= f.commit_button :label => "Go", :button_html => { :class => 'pretty', :accesskey => 'g', :disable_with => "Wait..." } %>
+      #   <%= f.commit_button "Go", :button_html => { :class => 'pretty', :accesskey => 'g', :disable_with => "Wait..." } %>
+      #
+      # @example Pass HTML attributes down to the `<li>` wrapper
+      #   <%= f.commit_button :wrapper_html => { :class => 'special', :id => 'whatever' } %>
+      #   <%= f.commit_button :label => "Go", :wrapper_html => { :class => 'special', :id => 'whatever' } %>
+      #   <%= f.commit_button "Go", :wrapper_html => { :class => 'special', :id => 'whatever' } %>
+      #
+      # @option *args :label [String, Symbol]
+      #   Override the label text with a String or a symbold for an i18n translation key
+      #
+      # @option *args :button_html [Hash]
+      #   Override or add to the HTML attributes to be passed down to the `<input>` tag
+      #
+      # @option *args :wrapper_html [Hash]
+      #   Override or add to the HTML attributes to be passed down to the wrapping `<li>` tag
+      #
+      # @todo document i18n keys
+      # @todo strange that `:accesskey` seems to be supported in the top level args as well as `:button_html`
+      def commit_button(*args)
+        options = args.extract_options!
+        text = options.delete(:label) || args.shift
+
+        if @object && (@object.respond_to?(:persisted?) || @object.respond_to?(:new_record?))
+          key = @object.persisted? ? :update : :create
+
+          # Deal with some complications with ActiveRecord::Base.human_name and two name models (eg UserPost)
+          # ActiveRecord::Base.human_name falls back to ActiveRecord::Base.name.humanize ("Userpost")
+          # if there's no i18n, which is pretty crappy.  In this circumstance we want to detect this
+          # fall back (human_name == name.humanize) and do our own thing name.underscore.humanize ("User Post")
+          if @object.class.model_name.respond_to?(:human)
+            object_name = @object.class.model_name.human
+          else
+            object_human_name = @object.class.human_name                # default is UserPost => "Userpost", but i18n may do better ("User post")
+            crappy_human_name = @object.class.name.humanize             # UserPost => "Userpost"
+            decent_human_name = @object.class.name.underscore.humanize  # UserPost => "User post"
+            object_name = (object_human_name == crappy_human_name) ? decent_human_name : object_human_name
+          end
+        else
+          key = :submit
+          object_name = @object_name.to_s.send(label_str_method)
+        end
+
+        text = (localized_string(key, text, :action, :model => object_name) ||
+                Formtastic::I18n.t(key, :model => object_name)) unless text.is_a?(::String)
+
+        button_html = options.delete(:button_html) || {}
+        button_html.merge!(:class => [button_html[:class], key].compact.join(' '))
+
+        wrapper_html_class = ['commit', 'button'] # TODO: Add class reflecting on form action.
+        wrapper_html = options.delete(:wrapper_html) || {}
+        wrapper_html[:class] = (wrapper_html_class << wrapper_html[:class]).flatten.compact.join(' ')
+
+        accesskey = (options.delete(:accesskey) || default_commit_button_accesskey) unless button_html.has_key?(:accesskey)
+        button_html = button_html.merge(:accesskey => accesskey) if accesskey
+        template.content_tag(:li, Formtastic::Util.html_safe(submit(text, button_html)), wrapper_html)
+      end
+    end
+  end
+end

data/lib/formtastic/helpers/errors_helper.rb

@@ -0,0 +1,113 @@
+module Formtastic
+  module Helpers
+    module ErrorsHelper
+      include Formtastic::Helpers::FileColumnDetection
+      include Formtastic::Helpers::Reflection
+      include Formtastic::LocalizedString
+
+      INLINE_ERROR_TYPES = [:sentence, :list, :first]
+
+      # Generates an unordered list of error messages on the base object and optionally for a given
+      # set of named attribute. This is idea for rendering a block of error messages at the top of
+      # the form for hidden/special/virtual attributes (the Paperclip Rails plugin does this), or
+      # errors on the base model.
+      #
+      # A hash can be used as the last set of arguments to pass HTML attributes to the `<ul>`
+      # wrapper.
+      #
+      # @example A list of errors on the base model
+      #   <%= semantic_form_for ... %>
+      #     <%= f.semantic_errors %>
+      #     ...
+      #   <% end %>
+      #
+      # @example A list of errors on the base and named attributes
+      #   <%= semantic_form_for ... %>
+      #     <%= f.semantic_errors :something_special %>
+      #     ...
+      #   <% end %>
+      #
+      # @example A list of errors on the base model, with custom HTML attributes
+      #   <%= semantic_form_for ... %>
+      #     <%= f.semantic_errors :class => "awesome" %>
+      #     ...
+      #   <% end %>
+      #
+      # @example A list of errors on the base model and named attributes, with custom HTML attributes
+      #   <%= semantic_form_for ... %>
+      #     <%= f.semantic_errors :something_special, :something_else, :class => "awesome", :onclick => "Awesome();" %>
+      #     ...
+      #   <% end %>
+      def semantic_errors(*args)
+        html_options = args.extract_options!
+        args = args - [:base]
+        full_errors = args.inject([]) do |array, method|
+          attribute = localized_string(method, method.to_sym, :label) || humanized_attribute_name(method)
+          errors = Array(@object.errors[method.to_sym]).to_sentence
+          errors.present? ? array << [attribute, errors].join(" ") : array ||= []
+        end
+        full_errors << @object.errors[:base]
+        full_errors.flatten!
+        full_errors.compact!
+        return nil if full_errors.blank?
+        html_options[:class] ||= "errors"
+        template.content_tag(:ul, html_options) do
+          Formtastic::Util.html_safe(full_errors.map { |error| template.content_tag(:li, Formtastic::Util.html_safe(error)) }.join)
+        end
+      end
+      
+      # Generates error messages for the given method, used for displaying errors right near the
+      # field for data entry. Uses the `:inline_errors` config to determin the right presentation,
+      # which may be an ordered list, a paragraph sentence containing all errors, or a paragraph
+      # containing just the first error. If configred to `:none`, no error is shown.
+      #
+      # See the `:inline_errors` config documentation for more details.
+      #
+      # This method is mostly used internally, but can be used in your forms when creating your own
+      # custom inputs, so it's been made public and aliased to `errors_on`.
+      #
+      # @example
+      #   <%= semantic_form_for @post do |f| %>
+      #     <li class='my-custom-text-input'>
+      #       <%= f.label(:body) %>
+      #       <%= f.text_field(:body) %>
+      #       <%= f.errors_on(:body) %>
+      #     </li>
+      #   <% end %>
+      #
+      # @deprecated See the README for the currently supported approach to custom inputs.
+      def inline_errors_for(method, options = {})
+        ActiveSupport::Deprecation.warn('inline_errors_for and errors_on are deprecated and will be removed on or after version 2.1', caller)
+        if render_inline_errors?
+          errors = error_keys(method, options).map{|x| @object.errors[x] }.flatten.compact.uniq
+          send(:"error_#{inline_errors}", [*errors], options) if errors.any?
+        else
+          nil
+        end
+      end
+      alias :errors_on :inline_errors_for
+      
+
+      protected
+
+      def error_keys(method, options)
+        @methods_for_error ||= {}
+        @methods_for_error[method] ||= begin
+          methods_for_error = [method.to_sym]
+          methods_for_error << file_metadata_suffixes.map{|suffix| "#{method}_#{suffix}".to_sym} if is_file?(method, options)
+          methods_for_error << [association_primary_key_for_method(method)] if [:belongs_to, :has_many].include? association_macro_for_method(method)
+          methods_for_error.flatten.compact.uniq
+        end
+      end
+
+      def has_errors?(method, options)
+        methods_for_error = error_keys(method,options)
+        @object && @object.respond_to?(:errors) && methods_for_error.any?{|error| !@object.errors[error].blank?}
+      end
+
+      def render_inline_errors?
+        @object && @object.respond_to?(:errors) && Formtastic::FormBuilder::INLINE_ERROR_TYPES.include?(inline_errors)
+      end
+    end
+  end
+end