formtastic 1.2.4 → 3.1.5

data/lib/formtastic/helpers/enum.rb

@@ -0,0 +1,13 @@
+module Formtastic
+  module Helpers
+    # @private
+    module Enum
+      # Returns the enum (if defined) for the given method
+      def enum_for(method) # @private
+        if @object.respond_to?(:defined_enums)
+          @object.defined_enums[method.to_s]
+        end
+      end
+    end
+  end
+end

data/lib/formtastic/helpers/errors_helper.rb

@@ -0,0 +1,81 @@
+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
+      
+      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

data/lib/formtastic/helpers/fieldset_wrapper.rb

@@ -0,0 +1,80 @@
+module Formtastic
+  module Helpers
+    # @private
+    module FieldsetWrapper
+
+      protected
+
+      # Generates a fieldset and wraps the content in an ordered list. When working
+      # with nested attributes, it allows %i as interpolation option in :name. So you can do:
+      #
+      #   f.inputs :name => 'Task #%i', :for => :tasks
+      #
+      # or the shorter equivalent:
+      #
+      #   f.inputs 'Task #%i', :for => :tasks
+      #
+      # And it will generate a fieldset for each task with legend 'Task #1', 'Task #2',
+      # 'Task #3' and so on.
+      #
+      # Note: Special case for the inline inputs (non-block):
+      #   f.inputs "My little legend", :title, :body, :author   # Explicit legend string => "My little legend"
+      #   f.inputs :my_little_legend, :title, :body, :author    # Localized (118n) legend with I18n key => I18n.t(:my_little_legend, ...)
+      #   f.inputs :title, :body, :author                       # First argument is a column => (no legend)
+      def field_set_and_list_wrapping(*args, &block) # @private
+        contents = args[-1].is_a?(::Hash) ? '' : args.pop.flatten
+        html_options = args.extract_options!
+
+        if block_given?
+          contents = if template.respond_to?(:is_haml?) && template.is_haml?
+            template.capture_haml(&block)
+          else
+            template.capture(&block)
+          end
+        end
+
+        # Ruby 1.9: String#to_s behavior changed, need to make an explicit join.
+        contents = contents.join if contents.respond_to?(:join)
+
+        legend = field_set_legend(html_options)
+        fieldset = template.content_tag(:fieldset,
+          Formtastic::Util.html_safe(legend) << template.content_tag(:ol, Formtastic::Util.html_safe(contents)),
+          html_options.except(:builder, :parent, :name)
+        )
+
+        fieldset
+      end
+
+      def field_set_legend(html_options)
+        legend  = (html_options[:name] || '').to_s
+        legend %= parent_child_index(html_options[:parent]) if html_options[:parent] && legend.include?('%i') # only applying if String includes '%i' avoids argument error when $DEBUG is true
+        legend  = template.content_tag(:legend, template.content_tag(:span, Formtastic::Util.html_safe(legend))) unless legend.blank?
+        legend
+      end
+
+      # Gets the nested_child_index value from the parent builder. It returns a hash with each
+      # association that the parent builds.
+      def parent_child_index(parent) # @private
+        # Could be {"post[authors_attributes]"=>0} or { :authors => 0 }
+        duck = parent[:builder].instance_variable_get('@nested_child_index')
+
+        # Could be symbol for the association, or a model (or an array of either, I think? TODO)
+        child = parent[:for]
+        # Pull a sybol or model out of Array (TODO: check if there's an Array)
+        child = child.first if child.respond_to?(:first)
+        # If it's an object, get a symbol from the class name
+        child = child.class.name.underscore.to_sym unless child.is_a?(Symbol)
+
+        key = "#{parent[:builder].object_name}[#{child}_attributes]"
+
+        # TODO: One of the tests produces a scenario where duck is "0" and the test looks for a "1"
+        # in the legend, so if we have a number, return it with a +1 until we can verify this scenario.
+        return duck + 1 if duck.is_a?(Integer)
+
+        # First try to extract key from duck Hash, then try child
+        (duck[key] || duck[child]).to_i + 1
+      end
+
+    end
+  end
+end

data/lib/formtastic/helpers/file_column_detection.rb

@@ -0,0 +1,16 @@
+module Formtastic
+  module Helpers
+    # @private
+    module FileColumnDetection
+
+      def is_file?(method, options = {})
+        @files ||= {}
+        @files[method] ||= (options[:as].present? && options[:as] == :file) || begin
+          file = @object.send(method) if @object && @object.respond_to?(method)
+          file && file_methods.any?{|m| file.respond_to?(m)}
+        end
+      end
+
+    end
+  end
+end

data/lib/formtastic/helpers/form_helper.rb

@@ -0,0 +1,203 @@
+module Formtastic
+  module Helpers
+
+    # FormHelper provides a handful of wrappers around Rails' built-in form helpers methods to set
+    # the `:builder` option to `Formtastic::FormBuilder` and apply some class names to the `<form>`
+    # tag.
+    #
+    # The following methods are wrapped:
+    #
+    # * `semantic_form_for` to `form_for`
+    # * `semantic_fields_for` to `fields_for`
+    # * `semantic_remote_form_for` and `semantic_form_remote_for` to `remote_form_for`
+    #
+    # The following two examples are effectively equivalent:
+    #
+    #     <%= form_for(@post, :builder => Formtastic::FormBuilder, :class => 'formtastic post') do |f| %>
+    #       #...
+    #     <% end %>
+    #
+    #     <%= semantic_form_for(@post) do |f| %>
+    #       #...
+    #     <% end %>
+    #
+    # This simple wrapping means that all arguments, options and variations supported by Rails' own
+    # helpers are also supported by Formtastic.
+    #
+    # Since `Formtastic::FormBuilder` subclasses Rails' own `FormBuilder`, you have access to all
+    # of Rails' built-in form helper methods such as `text_field`, `check_box`, `radio_button`,
+    # etc **in addition to** all of Formtastic's additional helpers like {InputsHelper#inputs inputs},
+    # {InputsHelper#input input}, {ButtonsHelper#buttons buttons}, etc:
+    #
+    #     <%= semantic_form_for(@post) do |f| %>
+    #
+    #       <!-- Formtastic -->
+    #       <%= f.input :title %>
+    #
+    #       <!-- Rails -->
+    #       <li class='something-custom'>
+    #         <%= f.label :title %>
+    #         <%= f.text_field :title %>
+    #         <p class='hints'>...</p>
+    #       </li>
+    #     <% end %>
+    #
+    # Formtastic is a superset of Rails' FormBuilder. It deliberately avoids overriding or modifying
+    # the behavior of Rails' own form helpers so that you can use Formtastic helpers when suited,
+    # and fall back to regular Rails helpers, ERB and HTML when needed. In other words, you're never
+    # fully committed to The Formtastic Way.
+    module FormHelper
+
+      # Allows the `:builder` option on `form_for` etc to be changed to your own which subclasses
+      # `Formtastic::FormBuilder`. Change this from `config/initializers/formtastic.rb`.
+      @@builder = Formtastic::FormBuilder
+      mattr_accessor :builder
+
+      # Allows the default class we add to all `<form>` tags to be changed from `formtastic` to
+      # `whatever`. Change this from `config/initializers/formtastic.rb`.
+      @@default_form_class = 'formtastic'
+      mattr_accessor :default_form_class
+
+      # Allows to set a custom proc to handle the class infered from the model's name. By default it
+      # will infer the name from the class name (eg. Post will be "post").
+      @@default_form_model_class_proc = proc { |model_class_name| model_class_name }
+      mattr_accessor :default_form_model_class_proc
+
+      # Allows to set a custom field_error_proc wrapper. By default this wrapper
+      # is disabled since `formtastic` already adds an error class to the LI tag
+      # containing the input. Change this from `config/initializers/formtastic.rb`.
+      @@formtastic_field_error_proc = proc { |html_tag, instance_tag| html_tag }
+      mattr_accessor :formtastic_field_error_proc
+
+      # Wrapper around Rails' own `form_for` helper to set the `:builder` option to
+      # `Formtastic::FormBuilder` and to set some class names on the `<form>` tag such as
+      # `formtastic` and the downcased and underscored model name (eg `post`).
+      #
+      # See Rails' `form_for` for full documentation of all supported arguments and options.
+      #
+      # Since `Formtastic::FormBuilder` subclasses Rails' own FormBuilder, you have access to all
+      # of Rails' built-in form helper methods such as `text_field`, `check_box`, `radio_button`,
+      # etc **in addition to** all of Formtastic's additional helpers like {InputsHelper#inputs inputs},
+      # {InputsHelper#input input}, {ButtonsHelper#buttons buttons}, etc.
+      #
+      # Most of the examples below have been adapted from the examples found in the Rails `form_for`
+      # documentation.
+      #
+      # @see http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html Rails' FormHelper documentation (`form_for`, etc)
+      # @see http://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html Rails' FormBuilder documentaion (`text_field`, etc)
+      # @see FormHelper The overview of the FormBuilder module
+      #
+      # @example Resource-oriented form generation
+      #   <%= semantic_form_for @user do |f| %>
+      #     <%= f.input :name %>
+      #     <%= f.input :email %>
+      #     <%= f.input :password %>
+      #   <% end %>
+      #
+      # @example Generic form generation
+      #   <%= semantic_form_for :user do |f| %>
+      #     <%= f.input :name %>
+      #     <%= f.input :email %>
+      #     <%= f.input :password %>
+      #   <% end %>
+      #
+      # @example Resource-oriented with custom URL
+      #   <%= semantic_form_for(@post, :url => super_post_path(@post)) do |f| %>
+      #     ...
+      #   <% end %>
+      #
+      # @example Resource-oriented with namespaced routes
+      #   <%= semantic_form_for([:admin, @post]) do |f| %>
+      #     ...
+      #   <% end %>
+      #
+      # @example Resource-oriented with nested routes
+      #   <%= semantic_form_for([@user, @post]) do |f| %>
+      #     ...
+      #   <% end %>
+      #
+      # @example Rename the resource
+      #   <%= semantic_form_for(@post, :as => :article) do |f| %>
+      #     ...
+      #   <% end %>
+      #
+      # @example Remote forms (unobtrusive JavaScript)
+      #   <%= semantic_form_for(@post, :remote => true) do |f| %>
+      #     ...
+      #   <% end %>
+      #
+      # @example Namespaced forms all multiple Formtastic forms to exist on the one page without DOM id clashes and invalid HTML documents.
+      #   <%= semantic_form_for(@post, :namespace => 'first') do |f| %>
+      #     ...
+      #   <% end %>
+      #
+      # @example Accessing a mixture of Formtastic helpers and Rails FormBuilder helpers.
+      #   <%= semantic_form_for(@post) do |f| %>
+      #     <%= f.input :title %>
+      #     <%= f.input :body %>
+      #     <li class="something-custom">
+      #       <label><%= f.check_box :published %></label>
+      #     </li>
+      #   <% end %>
+      #
+      # @param record_or_name_or_array
+      #   Same behavior as Rails' `form_for`
+      #
+      # @option *args [Hash] :html
+      #   Pass HTML attributes into the `<form>` tag. Same behavior as Rails' `form_for`, except we add in some of our own classes.
+      #
+      # @option *args [String, Hash] :url
+      #   A hash of URL components just like you pass into `link_to` or `url_for`, or a named route (eg `posts_path`). Same behavior as Rails' `form_for`.
+      #
+      # @option *args [String] :namespace
+      def semantic_form_for(record_or_name_or_array, *args, &proc)
+        options = args.extract_options!
+        options[:builder] ||= @@builder
+        options[:html] ||= {}
+        options[:html][:novalidate] = !@@builder.perform_browser_validations unless options[:html].key?(:novalidate)
+        options[:custom_namespace] = options.delete(:namespace)
+
+        singularizer = defined?(ActiveModel::Naming.singular) ? ActiveModel::Naming.method(:singular) : ActionController::RecordIdentifier.method(:singular_class_name)
+
+        class_names = options[:html][:class] ? options[:html][:class].split(" ") : []
+        class_names << @@default_form_class
+        model_class_name = case record_or_name_or_array
+          when String, Symbol then record_or_name_or_array.to_s                                  # :post => "post"
+          when Array then options[:as] || singularizer.call(record_or_name_or_array[-1].class)  # [@post, @comment] # => "comment"
+          else options[:as] || singularizer.call(record_or_name_or_array.class)                  # @post => "post"
+        end
+        class_names << @@default_form_model_class_proc.call(model_class_name)
+
+        options[:html][:class] = class_names.compact.join(" ")
+
+        with_custom_field_error_proc do
+          self.form_for(record_or_name_or_array, *(args << options), &proc)
+        end
+      end
+
+      # Wrapper around Rails' own `fields_for` helper to set the `:builder` option to
+      # `Formtastic::FormBuilder`.
+      #
+      # @see #semantic_form_for
+      def semantic_fields_for(record_name, record_object = nil, options = {}, &block)
+        options, record_object = record_object, nil if record_object.is_a?(Hash) && record_object.extractable_options?
+        options[:builder] ||= @@builder
+        options[:custom_namespace] = options.delete(:namespace)
+
+        with_custom_field_error_proc do
+          self.fields_for(record_name, record_object, options, &block)
+        end
+      end
+
+      protected
+
+      def with_custom_field_error_proc(&block)
+        default_field_error_proc = ::ActionView::Base.field_error_proc
+        ::ActionView::Base.field_error_proc = @@formtastic_field_error_proc
+        yield
+      ensure
+        ::ActionView::Base.field_error_proc = default_field_error_proc
+      end
+    end
+  end
+end

data/lib/formtastic/helpers/input_helper.rb

@@ -0,0 +1,407 @@
+# -*- coding: utf-8 -*-
+module Formtastic
+  module Helpers
+
+    # {#input} is used to render all content (labels, form widgets, error messages, hints, etc) for
+    # a single form input (or field), usually representing a single method or attribute on the
+    # form's object or model.
+    #
+    # The content is wrapped in an `<li>` tag, so it's usually called inside an {Formtastic::Helpers::InputsHelper#inputs inputs} block
+    # (which renders an `<ol>` inside a `<fieldset>`), which should be inside a {Formtastic::Helpers::FormHelper#semantic_form_for `semantic_form_for`}
+    # block:
+    #
+    #     <%= semantic_form_for @post do |f| %>
+    #       <%= f.inputs do %>
+    #         <%= f.input :title %>
+    #         <%= f.input :body %>
+    #       <% end %>
+    #     <% end %>
+    #
+    # The HTML output will be something like:
+    #
+    #     <form class="formtastic" method="post" action="...">
+    #       <fieldset>
+    #         <ol>
+    #           <li class="string required" id="post_title_input">
+    #             ...
+    #           </li>
+    #           <li class="text required" id="post_body_input">
+    #             ...
+    #           </li>
+    #         </ol>
+    #       </fieldset>
+    #     </form>
+    #
+    # @see #input
+    # @see Formtastic::Helpers::InputsHelper#inputs
+    # @see Formtastic::Helpers::FormHelper#semantic_form_for
+    module InputHelper
+      INPUT_CLASS_DEPRECATION = 'configure Formtastic::FormBuilder.input_class_finder instead (upgrade guide on wiki: http://bit.ly/1F9QtKc )'.freeze
+      private_constant(:INPUT_CLASS_DEPRECATION)
+
+      include Formtastic::Helpers::Reflection
+      include Formtastic::Helpers::Enum
+      include Formtastic::Helpers::FileColumnDetection
+
+      # Returns a chunk of HTML markup for a given `method` on the form object, wrapped in
+      # an `<li>` wrapper tag with appropriate `class` and `id` attribute hooks for CSS and JS.
+      # In many cases, the contents of the wrapper will be as simple as a `<label>` and an `<input>`:
+      #
+      #     <%= f.input :title, :as => :string, :required => true %>
+      #
+      #     <li class="string required" id="post_title_input">
+      #       <label for="post_title">Title<abbr title="Required">*</abbr></label>
+      #       <input type="text" name="post[title]" value="" id="post_title" required="required">
+      #     </li>
+      #
+      # In other cases (like a series of checkboxes for a `has_many` relationship), the wrapper may
+      # include more complex markup, like a nested `<fieldset>` with a `<legend>` and an `<ol>` of
+      # checkbox/label pairs for each choice:
+      #
+      #     <%= f.input :categories, :as => :check_boxes, :collection => Category.active.ordered %>
+      #
+      #     <li class="check_boxes" id="post_categories_input">
+      #       <fieldset>
+      #         <legend>Categories</legend>
+      #         <ol>
+      #           <li>
+      #             <label><input type="checkbox" name="post[categories][1]" value="1"> Ruby</label>
+      #           </li>
+      #           <li>
+      #             <label><input type="checkbox" name="post[categories][2]" value="2"> Rails</label>
+      #           </li>
+      #           <li>
+      #             <label><input type="checkbox" name="post[categories][2]" value="2"> Awesome</label>
+      #           </li>
+      #         </ol>
+      #       </fieldset>
+      #     </li>
+      #
+      # Sensible defaults for all options are guessed by looking at the method name, database column
+      # information, association information, validation information, etc. For example, a `:string`
+      # database column will map to a `:string` input, but if the method name contains 'email', will
+      # map to an `:email` input instead. `belongs_to` associations will have a `:select` input, etc.
+      #
+      # Formtastic supports many different styles of inputs, and you can/should override the default
+      # with the `:as` option. Internally, the symbol is used to map to a protected method
+      # responsible for the details. For example, `:as => :string` will map to `string_input`,
+      # defined in a module of the same name. Detailed documentation for each input style and it's
+      # supported options is available on the `*_input` method in each module (links provided below).
+      #
+      # Available input styles:
+      #
+      # * `:boolean`          (see {Inputs::BooleanInput})
+      # * `:check_boxes`      (see {Inputs::CheckBoxesInput})
+      # * `:color`            (see {Inputs::ColorInput})
+      # * `:country`          (see {Inputs::CountryInput})
+      # * `:datetime_select`  (see {Inputs::DatetimeSelectInput})
+      # * `:date_select`      (see {Inputs::DateSelectInput})
+      # * `:email`            (see {Inputs::EmailInput})
+      # * `:file`             (see {Inputs::FileInput})
+      # * `:hidden`           (see {Inputs::HiddenInput})
+      # * `:number`           (see {Inputs::NumberInput})
+      # * `:password`         (see {Inputs::PasswordInput})
+      # * `:phone`            (see {Inputs::PhoneInput})
+      # * `:radio`            (see {Inputs::RadioInput})
+      # * `:search`           (see {Inputs::SearchInput})
+      # * `:select`           (see {Inputs::SelectInput})
+      # * `:string`           (see {Inputs::StringInput})
+      # * `:text`             (see {Inputs::TextInput})
+      # * `:time_zone`        (see {Inputs::TimeZoneInput})
+      # * `:time_select`      (see {Inputs::TimeSelectInput})
+      # * `:url`              (see {Inputs::UrlInput})
+      #
+      # Calling `:as => :string` (for example) will call `#to_html` on a new instance of
+      # `Formtastic::Inputs::StringInput`. Before this, Formtastic will try to instantiate a top-level
+      # namespace StringInput, meaning you can subclass and modify `Formtastic::Inputs::StringInput`
+      # in `app/inputs/`. This also means you can create your own new input types in `app/inputs/`.
+      #
+      # @todo document the "guessing" of input style
+      #
+      # @param [Symbol] method
+      #   The database column or method name on the form object that this input represents
+      #
+      # @option options :as [Symbol]
+      #   Override the style of input should be rendered
+      #
+      # @option options :label [String, Symbol, false]
+      #   Override the label text
+      #
+      # @option options :hint [String, Symbol, false]
+      #   Override hint text
+      #
+      # @option options :required [Boolean]
+      #   Override to mark the input as required (or not) — adds a required/optional class to the wrapper, and a HTML5 required attribute to the `<input>`
+      #
+      # @option options :input_html [Hash]
+      #   Override or add to the HTML attributes to be passed down to the `<input>` tag
+      #   (If you use attr_readonly method in your model, formtastic will automatically set those attributes's input readonly)
+      #
+      # @option options :wrapper_html [Hash]
+      #   Override or add to the HTML attributes to be passed down to the wrapping `<li>` tag
+      #
+      # @option options :collection [Array<ActiveModel, String, Symbol>, Hash{String => String, Boolean}, OrderedHash{String => String, Boolean}]
+      #   Override collection of objects in the association (`:select`, `:radio` & `:check_boxes` inputs only)
+      #
+      # @option options :multiple [Boolean]
+      #   Specify if the `:select` input should allow multiple selections or not (defaults to `belongs_to` associations, and `true` for `has_many` and `has_and_belongs_to_many` associations)
+      #
+      # @option options :include_blank [Boolean]
+      #   Specify if a `:select` input should include a blank option or not (defaults to `include_blank_for_select_by_default` configuration)
+      #
+      # @option options :prompt [String]
+      #   Specify the text in the first ('blank') `:select` input `<option>` to prompt a user to make a selection (implicitly sets `:include_blank` to `true`)
+      #
+      # @todo Can we deprecate & kill `:label`, `:hint` & `:prompt`? All strings could be shifted to i18n!
+      #
+      # @example Accept all default options
+      #   <%= f.input :title %>
+      #
+      # @example Change the input type
+      #   <%= f.input :title, :as => :string %>
+      #
+      # @example Changing the label with a String
+      #   <%= f.input :title, :label => "Post title" %>
+      #
+      # @example Disabling the label with false, even if an i18n translation exists
+      #   <%= f.input :title, :label => false  %>
+      #
+      # @example Changing the hint with a String
+      #   <%= f.input :title, :hint => "Every post needs a title!" %>
+      #
+      # @example Disabling the hint with false, even if an i18n translation exists
+      #   <%= f.input :title, :hint => false  %>
+      #
+      # @example Marking a field as required or not (even if validations do not enforce it)
+      #   <%= f.input :title, :required => true  %>
+      #   <%= f.input :title, :required => false  %>
+      #
+      # @example Changing or adding to HTML attributes in the main `<input>` or `<select>` tag
+      #   <%= f.input :title, :input_html => { :onchange => "somethingAwesome();", :class => 'awesome' } %>
+      #
+      # @example Changing or adding to HTML attributes in the wrapper `<li>` tag
+      #   <%= f.input :title, :wrapper_html => { :class => "important-input" } %>
+      #
+      # @example Changing the association choices with `:collection`
+      #   <%= f.input :author,     :collection => User.active %>
+      #   <%= f.input :categories, :collection => Category.where(...).order(...) %>
+      #   <%= f.input :status,     :collection => ["Draft", "Published"] %>
+      #   <%= f.input :status,     :collection => [:draft, :published] %>
+      #   <%= f.input :status,     :collection => {"Draft" => 0, "Published" => 1} %>
+      #   <%= f.input :status,     :collection => OrderedHash.new("Draft" => 0, "Published" => 1) %>
+      #   <%= f.input :status,     :collection => [["Draft", 0], ["Published", 1]] %>
+      #   <%= f.input :status,     :collection => grouped_options_for_select(...) %>
+      #   <%= f.input :status,     :collection => options_for_select(...) %>
+      #
+      # @example Specifying if a `:select` should allow multiple selections:
+      #   <%= f.input :cateogies, :as => :select, :multiple => true %>
+      #   <%= f.input :cateogies, :as => :select, :multiple => false %>
+      #
+      # @example Specifying if a `:select` should have a 'blank' first option to prompt selection:
+      #   <%= f.input :author, :as => :select, :include_blank => true %>
+      #   <%= f.input :author, :as => :select, :include_blank => false %>
+      #
+      # @example Specifying the text for a `:select` input's 'blank' first option to prompt selection:
+      #   <%= f.input :author, :as => :select, :prompt => "Select an Author" %>
+      #
+      # @example Modifying an input to suit your needs in `app/inputs`:
+      #   class StringInput < Formtastic::Inputs::StringInput
+      #     def to_html
+      #       puts "this is my custom version of StringInput"
+      #       super
+      #     end
+      #   end
+      #
+      # @example Creating your own input to suit your needs in `app/inputs`:
+      #   class DatePickerInput
+      #     include Formtastic::Inputs::Base
+      #     def to_html
+      #       # ...
+      #     end
+      #   end
+      #
+      # @example Providing HTML5 placeholder text through i18n:
+      #   en:
+      #    formtastic:
+      #      placeholders:
+      #        user:
+      #          email: "you@yours.com"
+      #          first_name: "Joe"
+      #          last_name: "Smith"
+      #
+      # @see #namespaced_input_class
+      # @todo Many many more examples. Some of the detail probably needs to be pushed out to the relevant methods too.
+      # @todo More i18n examples.
+      def input(method, options = {})
+        method = method.to_sym
+        options = options.dup # Allow options to be shared without being tainted by Formtastic
+        options[:as] ||= default_input_type(method, options)
+
+        klass = input_class(options[:as])
+
+        klass.new(self, template, @object, @object_name, method, options).to_html
+      end
+
+      protected
+
+      # First try if we can detect special things like :file. With CarrierWave the method does have
+      # an underlying column so we don't want :string to get selected.
+      #
+      # For methods that have a database column, take a best guess as to what the input method
+      # should be.  In most cases, it will just return the column type (eg :string), but for special
+      # cases it will simplify (like the case of :integer, :float & :decimal to :number), or do
+      # something different (like :password and :select).
+      #
+      # If there is no column for the method (eg "virtual columns" with an attr_accessor), the
+      # default is a :string, a similar behaviour to Rails' scaffolding.
+      def default_input_type(method, options = {}) # @private
+        if @object
+          return :select  if reflection_for(method)
+
+          return :file    if is_file?(method, options)
+        end
+
+        column = column_for(method)
+        if column && column.type
+          # Special cases where the column type doesn't map to an input method.
+          case column.type
+          when :string
+            return :password  if method.to_s =~ /password/
+            return :country   if method.to_s =~ /country$/
+            return :time_zone if method.to_s =~ /time_zone/
+            return :email     if method.to_s =~ /email/
+            return :url       if method.to_s =~ /^url$|^website$|_url$/
+            return :phone     if method.to_s =~ /(phone|fax)/
+            return :search    if method.to_s =~ /^search$/
+            return :color     if method.to_s =~ /color/
+          when :integer
+            return :select    if reflection_for(method)
+            return :select    if enum_for(method)
+            return :number
+          when :float, :decimal
+            return :number
+          when :datetime, :timestamp
+            return :datetime_select
+          when :time
+            return :time_select
+          when :date
+            return :date_select
+          end
+
+          # Try look for hints in options hash. Quite common senario: Enum keys stored as string in the database.
+          return :select    if column.type == :string && options.key?(:collection)
+          # Try 3: Assume the input name will be the same as the column type (e.g. string_input).
+          return column.type
+        else
+          return :select    if options.key?(:collection)
+          return :password  if method.to_s =~ /password/
+          return :string
+        end
+      end
+
+      # Get a column object for a specified attribute method - if possible.
+      def column_for(method) # @private
+        if @object.respond_to?(:column_for_attribute)
+          # Remove deprecation wrapper & review after Rails 5.0 ships
+          ActiveSupport::Deprecation.silence do
+            @object.column_for_attribute(method)
+          end
+        end
+      end
+
+      # Takes the `:as` option and attempts to return the corresponding input
+      # class. In the case of `:as => :awesome` it will first attempt to find a
+      # top level `AwesomeInput` class (to allow the application to subclass
+      # and modify to suit), falling back to `Formtastic::Inputs::AwesomeInput`.
+      #
+      # Custom input namespaces to look into can be configured via the
+      # {Formtastic::FormBuilder.input_namespaces} configuration setting.
+      #
+      # @param [Symbol] as A symbol representing the type of input to render
+      # @raise [Formtastic::UnknownInputError] An appropriate input class could not be found
+      # @return [Class] An input class constant
+      #
+      # @example Normal use
+      #   input_class(:string) #=> Formtastic::Inputs::StringInput
+      #   input_class(:date) #=> Formtastic::Inputs::DateInput
+      #
+      # @example When a top-level class is found
+      #   input_class(:string) #=> StringInput
+      #   input_class(:awesome) #=> AwesomeInput
+      # @see NamespacedClassFinder#find
+      def namespaced_input_class(as)
+        @input_class_finder ||= input_class_finder.new(self)
+        @input_class_finder.find(as)
+      rescue Formtastic::InputClassFinder::NotFoundError
+        raise Formtastic::UnknownInputError, "Unable to find input #{$!.message}"
+      end
+
+      # @api private
+      # @deprecated Use {#namespaced_input_class} instead.
+      def input_class(as)
+        return namespaced_input_class(as) if input_class_finder
+
+        input_class_deprecation_warning(__method__)
+
+        @input_classes_cache ||= {}
+        @input_classes_cache[as] ||= begin
+          config = Rails.application.config
+          use_const_defined = config.respond_to?(:eager_load) ? config.eager_load : config.cache_classes
+          use_const_defined ? input_class_with_const_defined(as) : input_class_by_trying(as)
+        end
+      end
+
+      # @api private
+      # @deprecated Use {InputClassFinder#find} instead.
+      # prevent exceptions in production environment for better performance
+      def input_class_with_const_defined(as)
+        input_class_name = custom_input_class_name(as)
+
+        if ::Object.const_defined?(input_class_name)
+          input_class_name.constantize
+        elsif Formtastic::Inputs.const_defined?(input_class_name)
+          standard_input_class_name(as).constantize
+        else
+          raise Formtastic::UnknownInputError, "Unable to find input class #{input_class_name}"
+        end
+      end
+
+      # @api private
+      # @deprecated Use {InputClassFinder#find} instead.
+      # use auto-loading in development environment
+      def input_class_by_trying(as)
+        begin
+          custom_input_class_name(as).constantize
+        rescue NameError
+          standard_input_class_name(as).constantize
+        end
+      rescue NameError
+        raise Formtastic::UnknownInputError, "Unable to find input class for #{as}"
+      end
+
+      # @api private
+      # @deprecated Use {InputClassFinder#class_name} instead.
+      # :as => :string # => StringInput
+      def custom_input_class_name(as)
+        input_class_deprecation_warning(__method__)
+        "#{as.to_s.camelize}Input"
+      end
+
+      # @api private
+      # @deprecated Use {InputClassFinder#class_name} instead.
+      # :as => :string # => {Formtastic::Inputs::StringInput}
+      def standard_input_class_name(as)
+        input_class_deprecation_warning(__method__)
+        "Formtastic::Inputs::#{as.to_s.camelize}Input"
+      end
+
+      private
+
+      def input_class_deprecation_warning(method)
+        @input_class_deprecation_warned ||=
+            Formtastic.deprecation.deprecation_warning(method, INPUT_CLASS_DEPRECATION, caller(2))
+      end
+
+    end
+  end
+end