formtastic 2.0.2 → 2.1.0.beta1

data/lib/formtastic/actions/link_action.rb

@@ -0,0 +1,87 @@
+# Outputs a link wrapped in the standard `<li>` wrapper. This the default for `:cancel` actions.
+# The link's URL defaults to Rails' built-in `:back` macro (the HTTP referrer, or Javascript for the
+# browser's history), but can be altered with the `:url` option.
+#
+# @example The `:as` can be ommitted, these are functionally equivalent
+#   <%= f.action :cancel, :as => :link %>
+#   <%= f.action :cancel %>
+#
+# @example Full form context and output
+#
+#   <%= semantic_form_for(@post) do |f| %>
+#     <%= f.actions do %>
+#       <%= f.action :submit, :as => :input %>
+#       <%= f.action :cancel, :as => :link %>
+#     <% end %>
+#   <% end %>
+#
+#   <form...>
+#     <fieldset class="actions">
+#       <ol>
+#         <li class="action input_action" id="post_submit_action">
+#           <input type="reset" value="Reset">
+#         </li>
+#         <li class="action link_action" id="post_reset_action">
+#           <a href="javascript:history.back()">Cancel</a>
+#         </li>
+#       </ol>
+#     </fieldset>
+#   </form>
+#
+# @example Modifying the URL for the link
+#   <%= f.action :cancel, :as => :link, :url => "http://example.com/path" %>
+#   <%= f.action :cancel, :as => :link, :url => "/path" %>
+#   <%= f.action :cancel, :as => :link, :url => posts_path %>
+#   <%= f.action :cancel, :as => :link, :url => url_for(...) %>
+#   <%= f.action :cancel, :as => :link, :url => { :controller => "posts", :action => "index" } %>
+#
+# @example Specifying a label with a String
+#   <%= f.action :cancel, :as => :link, :label => "Stop" %>
+#
+# @example Pass HTML attributes down to the `<a>`
+#   <%= f.action :cancel, :as => :link, :button_html => { :class => 'pretty', :accesskey => 'x' } %>
+#
+# @example Access key can also be set as a top-level option
+#   <%= f.action :cancel, :as => :link, :accesskey => 'x' %>
+#
+# @example Pass HTML attributes down to the `<li>` wrapper (classes are appended to the existing classes)
+#   <%= f.action :cancel, :as => :link, :wrapper_html => { :class => 'special', :id => 'whatever' } %>
+#   <%= f.action :cancel, :as => :link, :wrapper_html => { :class => ['extra', 'special'], :id => 'whatever' } %>
+#
+# @option *args :label [String, Symbol]
+#   Override the label text with a String or a symbol for an i18n translation key
+#
+# @option *args :button_html [Hash]
+#   Override or add to the HTML attributes to be passed down to the `<a>` 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 document i18n translation with :label (?)
+# @todo :prefix and :suffix options? (can also be done with CSS or subclassing for custom Actions)
+module Formtastic
+  module Actions
+    class LinkAction
+
+      include Base
+      
+      def supported_methods
+        [:cancel]
+      end
+      
+      # TODO reset_action class?
+      def to_html
+        wrapper do
+          template.link_to(text, url, button_html)
+        end
+      end
+      
+      def url
+        return options[:url] if options.key?(:url)
+        :back
+      end
+
+    end
+  end
+end

data/lib/formtastic/engine.rb

@@ -1,7 +1,11 @@
-# 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
+    initializer 'formtastic.initialize' do
+      ActiveSupport.on_load(:action_view) do
+        include Formtastic::Helpers::FormHelper
+      end
+    end
   end
 end

data/lib/formtastic/form_builder.rb

@@ -23,6 +23,7 @@ module Formtastic
     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_localizer, Formtastic::Localizer
     configure :escape_html_entities_in_hints_and_labels, true
     configure :default_commit_button_accesskey
     configure :default_inline_error_class, 'inline-errors'
@@ -40,6 +41,8 @@ module Formtastic
     include Formtastic::Helpers::InputHelper
     include Formtastic::Helpers::InputsHelper
     include Formtastic::Helpers::ButtonsHelper
+    include Formtastic::Helpers::ActionHelper
+    include Formtastic::Helpers::ActionsHelper
     include Formtastic::Helpers::ErrorsHelper
     
     # This is a wrapper around Rails' `ActionView::Helpers::FormBuilder#fields_for`, originally 

data/lib/formtastic/helpers.rb

@@ -2,6 +2,8 @@ module Formtastic
   # @private
   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'
@@ -9,7 +11,6 @@ module Formtastic
     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/action_helper.rb

@@ -0,0 +1,109 @@
+# -*- coding: utf-8 -*-
+module Formtastic
+  module Helpers
+    module ActionHelper
+      
+      # 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.
+      #
+      # @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 = {}) #:nodoc:
+        case method
+          when :submit then :input
+          when :reset then :input
+          when :cancel then :link
+        end
+      end
+
+      def action_class(as)
+        @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
+          end
+        end
+      end
+
+      # :as => :button # => ButtonAction
+      def custom_action_class_name(as)
+        "#{as.to_s.camelize}Action"
+      end
+
+      # :as => :button # => Formtastic::Actions::ButtonAction
+      def standard_action_class_name(as)
+        "Formtastic::Actions::#{as.to_s.camelize}Action"
+      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

data/lib/formtastic/helpers/buttons_helper.rb

@@ -22,7 +22,7 @@ module Formtastic
     #       ...
     #       <fieldset class="buttons">
     #         <ol>
-    #           <li class="commit">
+    #           <li class="commit button">
     #             <input type="submit" name="commit" value="Create Post" class="create">
     #           </li>
     #         </ol>
@@ -53,6 +53,8 @@ module Formtastic
     #
     # There are many other syntax variations and arguments to customize your form. See the
     # full documentation of {#buttons} and {#commit_button} for details.
+    #
+    # @deprecated ButtonsHelper will be removed after 2.1
     module ButtonsHelper
       include Formtastic::Helpers::FieldsetWrapper
       include Formtastic::LocalizedString
@@ -76,9 +78,9 @@ module Formtastic
       #
       #     # Output:
       #     <form ...>
-      #       <fieldset class="inputs">
+      #       <fieldset class="buttons">
       #         <ol>
-      #           <li class="commit">
+      #           <li class="commit button">
       #             <input type="submit" ...>
       #           </li>
       #         </ol>
@@ -164,7 +166,10 @@ module Formtastic
       #   Optionally specify text for the legend of the fieldset (alias for `:label`)
       #
       # @todo document i18n keys
+      # @deprecated f.buttons is deprecated in favor of f.actions and will be removed after 2.1
       def buttons(*args, &block)
+        ::ActiveSupport::Deprecation.warn("f.buttons is deprecated in favour of f.actions and will be removed from Formtastic after 2.1. Please see ActionsHelper and InputAction or ButtonAction for more information")
+        
         html_options = args.extract_options!
         html_options[:class] ||= "buttons"
 
@@ -203,7 +208,11 @@ module Formtastic
       #   <form ...>
       #     ...
       #     <fieldset class="buttons">
-      #       <input name="commit" type="submit" value="Create Post" class="create">
+      #       <ol>
+      #         <li class="commit button">
+      #           <input name="commit" type="submit" value="Create Post" class="create">
+      #         </li>
+      #       </ol>
       #     </fieldset>
       #   </form>
       #
@@ -234,7 +243,10 @@ module Formtastic
       #
       # @todo document i18n keys
       # @todo strange that `:accesskey` seems to be supported in the top level args as well as `:button_html`
+      # @deprecated f.commit_button is deprecated in favor of f.actions and will be removed after 2.1
       def commit_button(*args)
+        ::ActiveSupport::Deprecation.warn("f.commit_button is deprecated in favour of f.action(:submit) and will be removed from Formtastic after 2.1. Please see ActionsHelper and InputAction or ButtonAction for more information")
+        
         options = args.extract_options!
         text = options.delete(:label) || args.shift
 
@@ -242,6 +254,7 @@ module Formtastic
                 Formtastic::I18n.t(commit_button_i18n_key, :model => commit_button_object_name)) unless text.is_a?(::String)
 
         button_html = options.delete(:button_html) || {}
+        button_html[:id] ||= "#{@object_name}_submit"
         button_html.merge!(:class => [button_html[:class], commit_button_i18n_key].compact.join(' '))
 
         wrapper_html = options.delete(:wrapper_html) || {}
@@ -249,7 +262,7 @@ module Formtastic
 
         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
 
@@ -270,10 +283,10 @@ module Formtastic
         else
           object_name = @object_name.to_s.send(label_str_method)
         end
-        
+
         object_name
       end
-      
+
       def commit_button_i18n_key
         if new_or_persisted_object?
           key = @object.persisted? ? :update : :create
@@ -287,11 +300,11 @@ module Formtastic
       def commit_button_wrapper_html_class
         ['commit', 'button'] # TODO: Add class reflecting on form action.
       end
-      
+
       def new_or_persisted_object?
         @object && (@object.respond_to?(:persisted?) || @object.respond_to?(:new_record?))
       end
-      
+
     end
   end
 end