formtastic 1.2.4 → 3.1.5

data/lib/formtastic/engine.rb

@@ -0,0 +1,11 @@
+module Formtastic
+  # Required for formtastic.css to be discoverable in the asset pipeline
+  # @private
+  class Engine < ::Rails::Engine
+    initializer 'formtastic.initialize' do
+      ActiveSupport.on_load(:action_view) do
+        include Formtastic::Helpers::FormHelper
+      end
+    end
+  end
+end

data/lib/formtastic/form_builder.rb

@@ -0,0 +1,124 @@
+module Formtastic
+  class FormBuilder < ActionView::Helpers::FormBuilder
+
+    # Defines a new configurable option
+    # @param [Symbol] name the configuration name
+    # @param [Object] default the configuration default value
+    # @private
+    #
+    # @!macro [new] configure
+    #   @!scope class
+    #   @!attribute [rw] $1
+    #   @api public
+    def self.configure(name, default = nil)
+      class_attribute(name)
+      self.send(:"#{name}=", default)
+    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 :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 :i18n_cache_lookups, true
+    configure :i18n_localizer, Formtastic::Localizer
+    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'
+    configure :use_required_attribute, false
+    configure :perform_browser_validations, false
+    # Check {Formtastic::InputClassFinder} to see how are inputs resolved.
+    configure :input_namespaces, [::Object, ::Formtastic::Inputs]
+    # @todo enable this as default in 4.0 and remove it from configuration generator template
+    # Will be {Formtastic::InputClassFinder} by default in 4.0.
+    configure :input_class_finder #, Formtastic::InputClassFinder
+    # Check {Formtastic::ActionClassFinder} to see how are inputs resolved.
+    configure :action_namespaces, [::Object, ::Formtastic::Actions]
+    # @todo enable this as default in 4.0 and remove it from configuration generator template
+    # Will be {Formtastic::ActionClassFinder} by default in 4.0.
+    configure :action_class_finder#, Formtastic::ActionClassFinder
+
+    configure :skipped_columns, [:created_at, :updated_at, :created_on, :updated_on, :lock_version, :version]
+    configure :priority_time_zones, []
+
+    attr_reader :template
+
+    attr_reader :auto_index
+
+    include Formtastic::HtmlAttributes
+
+    include Formtastic::Helpers::InputHelper
+    include Formtastic::Helpers::InputsHelper
+    include Formtastic::Helpers::ActionHelper
+    include Formtastic::Helpers::ActionsHelper
+    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
+
+    def initialize(object_name, object, template, options, block=nil)
+      # rails 3 supported passing in the block parameter to FormBuilder
+      # rails 4.0 deprecated the block parameter and does nothing with it
+      # rails 4.1 removes the parameter completely
+      if Util.rails3? || Util.rails4_0?
+        super
+      else # Must be rails4_1 or greater
+        super object_name, object, template, options
+      end
+
+      if respond_to?('multipart=') && options.is_a?(Hash) && options[:html]
+        self.multipart = options[:html][:multipart]
+      end
+    end
+
+  end
+
+end
+

data/lib/formtastic/helpers.rb

@@ -0,0 +1,16 @@
+module Formtastic
+  module Helpers
+    autoload :ButtonsHelper, 'formtastic/helpers/buttons_helper'
+    autoload :ActionHelper, 'formtastic/helpers/action_helper'
+    autoload :ActionsHelper, 'formtastic/helpers/actions_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 :Reflection, 'formtastic/helpers/reflection'
+    autoload :Enum, 'formtastic/helpers/enum'
+  end
+end
+

data/lib/formtastic/helpers/action_helper.rb

@@ -0,0 +1,162 @@
+# -*- coding: utf-8 -*-
+module Formtastic
+  module Helpers
+    module ActionHelper
+      ACTION_CLASS_DEPRECATION = 'configure Formtastic::FormBuilder.action_class_finder instead (upgrade guide on wiki: http://bit.ly/1F9QtKc )'.freeze
+      private_constant(:ACTION_CLASS_DEPRECATION)
+
+      # Renders an action for the form (such as a subit/reset button, or a cancel link).
+      #
+      # Each action is wrapped in an `<li class="action">` tag with other classes added based on the
+      # type of action being rendered, 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 the default through the `:label`
+      # argument or through i18n.
+      #
+      # If using i18n, you'll need to provide the following translations:
+      #
+      #   en:
+      #     formtastic:
+      #       actions:
+      #         create: "Create new %{model}"
+      #         update: "Save %{model}"
+      #         cancel: "Cancel"
+      #         reset: "Reset form"
+      #         submit: "Submit"
+      #
+      # For forms with an object present, the `update` key will be used if calling `persisted?` on
+      # the object returns true (saving changes to a record), otherwise the `create` key will be
+      # used. The `submit` key is used as a fallback when there is no object or we cannot determine
+      # if `create` or `update` is appropriate.
+      #
+      # @example Basic usage
+      #   # form
+      #   <%= semantic_form_for @post do |f| %>
+      #     ...
+      #     <%= f.actions do %>
+      #       <%= f.action :submit %>
+      #       <%= f.action :reset %>
+      #       <%= f.action :cancel %>
+      #     <% end %>
+      #   <% end %>
+      #
+      #   # output
+      #   <form ...>
+      #     ...
+      #     <fieldset class="buttons">
+      #       <ol>
+      #         <li class="action input_action">
+      #           <input name="commit" type="submit" value="Create Post">
+      #         </li>
+      #         <li class="action input_action">
+      #           <input name="commit" type="reset" value="Reset Post">
+      #         </li>
+      #         <li class="action link_action">
+      #           <a href="/posts">Cancel Post</a>
+      #         </li>
+      #       </ol>
+      #     </fieldset>
+      #   </form>
+      #
+      # @example Set the value through the `:label` option
+      #   <%= f.action :submit, :label => "Go" %>
+      #
+      # @example Pass HTML attributes down to the tag inside the wrapper
+      #   <%= f.action :submit, :button_html => { :class => 'pretty', :accesskey => 'g', :disable_with => "Wait..." } %>
+      #
+      # @example Pass HTML attributes down to the `<li>` wrapper
+      #   <%= f.action :submit, :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
+      def action(method, options = {})
+        options = options.dup # Allow options to be shared without being tainted by Formtastic
+        options[:as] ||= default_action_type(method, options)
+
+        klass = action_class(options[:as])
+
+        klass.new(self, template, @object, @object_name, method, options).to_html
+      end
+
+      protected
+
+      def default_action_type(method, options = {}) # @private
+        case method
+          when :submit then :input
+          when :reset  then :input
+          when :cancel then :link
+          else method
+        end
+      end
+
+      # Takes the `:as` option and attempts to return the corresponding action
+      # class. In the case of `:as => :awesome` it will first attempt to find a
+      # top level `AwesomeAction` class (to allow the application to subclass
+      # and modify to suit), falling back to `Formtastic::Actions::AwesomeAction`.
+      #
+      # Custom action namespaces to look into can be configured via the
+      # {Formtastic::FormBuilder.action_namespaces} configuration setting.
+      # @see Helpers::InputHelper#namespaced_input_class
+      # @see Formtastic::ActionClassFinder
+      def namespaced_action_class(as)
+        @action_class_finder ||= action_class_finder.new(self)
+        @action_class_finder.find(as)
+      rescue Formtastic::ActionClassFinder::NotFoundError => e
+        raise Formtastic::UnknownActionError, "Unable to find action #{e.message}"
+      end
+
+      # @api private
+      # @deprecated Use {#namespaced_action_class} instead.
+      def action_class(as)
+        return namespaced_action_class(as) if action_class_finder
+
+        action_class_deprecation_warning(__method__)
+
+        @input_classes_cache ||= {}
+        @input_classes_cache[as] ||= begin
+          begin
+            begin
+              custom_action_class_name(as).constantize
+            rescue NameError
+              standard_action_class_name(as).constantize
+            end
+          rescue NameError
+            raise Formtastic::UnknownActionError, "Unable to find action #{as}"
+          end
+        end
+      end
+
+      # @api private
+      # @deprecated Use {Formtastic::ActionClassFinder#class_name} instead.
+      # :as => :button # => ButtonAction
+      def custom_action_class_name(as)
+        action_class_deprecation_warning(__method__)
+        "#{as.to_s.camelize}Action"
+      end
+
+      # @api private
+      # @deprecated Use {Formtastic::ActionClassFinder#class_name} instead.
+      # :as => :button # => Formtastic::Actions::ButtonAction
+      def standard_action_class_name(as)
+        action_class_deprecation_warning(__method__)
+        "Formtastic::Actions::#{as.to_s.camelize}Action"
+      end
+
+      private
+
+      def action_class_deprecation_warning(method)
+        @action_class_deprecation_warned ||=
+            Formtastic.deprecation.deprecation_warning(method, ACTION_CLASS_DEPRECATION, caller(2))
+      end
+    end
+  end
+end

data/lib/formtastic/helpers/actions_helper.rb

@@ -0,0 +1,168 @@
+module Formtastic
+  module Helpers
+    # ActionsHelper encapsulates the responsibilties of the {#actions} DSL for acting on 
+    # (submitting, cancelling, resetting) forms.
+    #
+    # {#actions} is a block helper used to wrap the form's actions (buttons, links) in a 
+    # `<fieldset>` and `<ol>`, with each item in the list containing the markup representing a 
+    # single action.
+    #
+    #     <%= semantic_form_for @post do |f| %>
+    #       ...
+    #       <%= f.actions do %>
+    #         <%= f.action :submit
+    #         <%= f.action :cancel
+    #       <% end %>
+    #     <% end %>
+    #
+    # The HTML output will be something like:
+    #
+    #     <form class="formtastic" method="post" action="...">
+    #       ...
+    #       <fieldset class="actions">
+    #         <ol>
+    #           <li class="action input_action">
+    #             <input type="submit" name="commit" value="Create Post">
+    #           </li>
+    #           <li class="action input_action">
+    #             <a href="/posts">Cancel Post</a>
+    #           </li>
+    #         </ol>
+    #       </fieldset>
+    #     </form>
+    #
+    # It's important to note that the `semantic_form_for` and {#actions} 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.actions 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 {#actions} and {#action} for details.
+    module ActionsHelper
+
+      include Formtastic::Helpers::FieldsetWrapper
+      
+      # 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 actions. These two examples are functionally equivalent:
+      #
+      #     # With a block:
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <% f.actions do %>
+      #         <%= f.action :submit %>
+      #         <%= f.action :cancel %>
+      #       <% end %>
+      #     <% end %>
+      #
+      #     # With a list of fields:
+      #     <% semantic_form_for @post do |f| %>
+      #       <%= f.actions :submit, :cancel %>
+      #     <% end %>
+      #
+      #     # Output:
+      #     <form ...>
+      #       <fieldset class="buttons">
+      #         <ol>
+      #           <li class="action input_action">
+      #             <input type="submit" ...>
+      #           </li>
+      #           <li class="action link_action">
+      #             <a href="...">...</a>
+      #           </li>
+      #         </ol>
+      #       </fieldset>
+      #     </form>
+      #
+      # 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.actions %>
+      #     <% end %>
+      #
+      # @example Specify which named buttons you want, accepting all default values, options and behaviors
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <%= f.actions :commit %>
+      #     <% end %>
+      #
+      # @example Specify which named buttons you want, and name the fieldset
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <%= f.actions :commit, :name => "Actions" %>
+      #       or
+      #       <%= f.actions :commit, :label => "Actions" %>
+      #     <% end %>
+      #
+      # @example Get full control over the action options
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <%= f.actions do %>
+      #         <%= f.action :label => "Go", :button_html => { :class => "pretty" :disable_with => "Wait..." }, :wrapper_html => { ... }
+      #       <% end %>
+      #     <% end %>
+      #
+      # @example Make your own actions with standard Rails helpers or HTML
+      #     <% semantic_form_for @post do |f| %>
+      #       <%= f.actions do %>
+      #         <li>
+      #           ...
+      #         </li>
+      #       <% end %>
+      #     <% end %>
+      #
+      # @example Add HTML attributes to the fieldset
+      #     <% semantic_form_for @post do |f| %>
+      #       ...
+      #       <%= f.actions :commit, :style => "border:1px;" %>
+      #       or
+      #       <%= f.actions :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 actions(*args, &block)
+        html_options = args.extract_options!
+        html_options[:class] ||= "actions"
+
+        if block_given?
+          field_set_and_list_wrapping(html_options, &block)
+        else
+          args = default_actions if args.empty?
+          contents = args.map { |action_name| action(action_name) }
+          field_set_and_list_wrapping(html_options, contents)
+        end
+      end
+
+      protected
+      
+      def default_actions
+        [:submit]
+      end
+
+    end
+  end
+end