Class: Formtastic::SemanticFormBuilder
- Inherits:
-
ActionView::Helpers::FormBuilder
- Object
- ActionView::Helpers::FormBuilder
- Formtastic::SemanticFormBuilder
- Defined in:
- lib/formtastic.rb
Constant Summary collapse
- RESERVED_COLUMNS =
[:created_at, :updated_at, :created_on, :updated_on, :lock_version, :version]
- INLINE_ERROR_TYPES =
[:sentence, :list, :first]
- @@default_text_field_size =
50
- @@default_text_area_height =
20
- @@all_fields_required_by_default =
true
- @@include_blank_for_select_by_default =
true
- @@required_string =
proc { ::Formtastic::Util.html_safe(%{<abbr title="#{::Formtastic::I18n.t(:required)}">*</abbr>}) }
- @@optional_string =
''
- @@inline_errors =
:sentence
- @@label_str_method =
:humanize
- @@collection_label_methods =
%w[to_label display_name full_name name title username login value to_s]
- @@inline_order =
[ :input, :hints, :errors ]
- @@file_methods =
[ :file?, :public_filename, :filename ]
- @@priority_countries =
["Australia", "Canada", "United Kingdom", "United States"]
- @@i18n_lookups_by_default =
false
nil
Instance Attribute Summary collapse
-
#template ⇒ Object
Returns the value of attribute template.
Instance Method Summary collapse
-
#buttons(*args, &block) ⇒ Object
(also: #button_field_set)
Creates a fieldset and ol tag wrapping for form buttons / actions as list items.
-
#commit_button(*args) ⇒ Object
Creates a submit input tag with the value “Save [model name]” (for existing records) or “Create [model name]” (for new records) by default:.
-
#inline_errors_for(method, options = nil) ⇒ Object
(also: #errors_on)
Generates error messages for the given method.
-
#input(method, options = {}) ⇒ Object
Returns a suitable form input for the given
method
, using the database column information and other factors (like the method name) to figure out what you probably want. -
#inputs(*args, &block) ⇒ Object
(also: #input_field_set)
Creates an input fieldset and ol tag wrapping for use around a set of inputs.
-
#label(method, options_or_text = nil, options = nil) ⇒ Object
Generates the label for the input.
-
#semantic_errors(*args) ⇒ Object
Generates error messages for given method names and for base.
-
#semantic_fields_for(record_or_name_or_array, *args, &block) ⇒ Object
A thin wrapper around #fields_for to set :builder => Formtastic::SemanticFormBuilder for nesting forms:.
Instance Attribute Details
#template ⇒ Object
Returns the value of attribute template.
33 34 35 |
# File 'lib/formtastic.rb', line 33 def template @template end |
Instance Method Details
#buttons(*args, &block) ⇒ Object Also known as:
Creates a fieldset and ol tag wrapping for form buttons / actions as list items. See inputs documentation for a full example. The fieldset’s default class attriute is set to “buttons”.
See inputs for html attributes and special options.
290 291 292 293 294 295 296 297 298 299 300 301 |
# File 'lib/formtastic.rb', line 290 def (*args, &block) = args. [:class] ||= "buttons" if block_given? field_set_and_list_wrapping(, &block) else args = [:commit] if args.empty? contents = args.map { || send(:"#{}_button") } field_set_and_list_wrapping(, contents) end end |
#commit_button(*args) ⇒ Object
Creates a submit input tag with the value “Save [model name]” (for existing records) or “Create [model name]” (for new records) by default:
<%= form.commit_button %> => <input name="commit" type="submit" value="Save Post" />
The value of the button text can be overridden:
<%= form.commit_button "Go" %> => <input name="commit" type="submit" value="Go" class="{create|update|submit}" />
<%= form.commit_button :label => "Go" %> => <input name="commit" type="submit" value="Go" class="{create|update|submit}" />
And you can pass html atributes down to the input, with or without the button text:
<%= form.commit_button "Go" %> => <input name="commit" type="submit" value="Go" class="{create|update|submit}" />
<%= form.commit_button :class => "pretty" %> => <input name="commit" type="submit" value="Save Post" class="pretty {create|update|submit}" />
319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 |
# File 'lib/formtastic.rb', line 319 def (*args) = args. text = .delete(:label) || args.shift if @object && @object.respond_to?(:new_record?) key = @object.new_record? ? :create : :update # 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 = (self.localized_string(key, text, :action, :model => object_name) || ::Formtastic::I18n.t(key, :model => object_name)) unless text.is_a?(::String) = .delete(:button_html) || {} .merge!(:class => [[:class], key].compact.join(' ')) element_class = ['commit', .delete(:class)].compact.join(' ') # TODO: Add class reflecting on form action. accesskey = (.delete(:accesskey) || @@default_commit_button_accesskey) unless .has_key?(:accesskey) = .merge(:accesskey => accesskey) if accesskey template.content_tag(:li, Formtastic::Util.html_safe(self.submit(text, )), :class => element_class) end |
#inline_errors_for(method, options = nil) ⇒ Object Also known as: errors_on
Generates error messages for the given method. Errors can be shown as list, as sentence or just the first error can be displayed. If :none is set, no error is shown.
This method is also aliased as errors_on, so you can call on your custom inputs as well:
semantic_form_for :post do |f|
f.text_field(:body)
f.errors_on(:body)
end
433 434 435 436 437 438 439 440 441 442 |
# File 'lib/formtastic.rb', line 433 def inline_errors_for(method, = nil) #:nodoc: if render_inline_errors? errors = [@object.errors[method.to_sym]] errors << [@object.errors[association_primary_key(method)]] if association_macro_for_method(method) == :belongs_to errors = errors.flatten.compact.uniq send(:"error_#{@@inline_errors}", [*errors]) if errors.any? else nil end end |
#input(method, options = {}) ⇒ Object
Returns a suitable form input for the given method
, using the database column information and other factors (like the method name) to figure out what you probably want.
Options:
-
:as - override the input type (eg force a :string to render as a :password field)
-
:label - use something other than the method name as the label text, when false no label is printed
-
:required - specify if the column is required (true) or not (false)
-
:hint - provide some text to hint or help the user provide the correct information for a field
-
:input_html - provide options that will be passed down to the generated input
-
:wrapper_html - provide options that will be passed down to the li wrapper
Input Types:
Most inputs map directly to one of ActiveRecord’s column types by default (eg string_input), but there are a few special cases and some simplification (:integer, :float and :decimal columns all map to a single numeric_input, for example).
-
:select (a select menu for associations) - default to association names
-
:check_boxes (a set of check_box inputs for associations) - alternative to :select has_many and has_and_belongs_to_many associations
-
:radio (a set of radio inputs for associations) - alternative to :select belongs_to associations
-
:time_zone (a select menu with time zones)
-
:password (a password input) - default for :string column types with ‘password’ in the method name
-
:text (a textarea) - default for :text column types
-
:date (a date select) - default for :date column types
-
:datetime (a date and time select) - default for :datetime and :timestamp column types
-
:time (a time select) - default for :time column types
-
:boolean (a checkbox) - default for :boolean column types (you can also have booleans as :select and :radio)
-
:string (a text field) - default for :string column types
-
:numeric (a text field, like string) - default for :integer, :float and :decimal column types
-
:country (a select menu of country names) - requires a country_select plugin to be installed
-
:hidden (a hidden field) - creates a hidden field (added for compatibility)
Example:
<% semantic_form_for @employee do |form| %>
<% form.inputs do -%>
<%= form.input :secret, :value => "Hello" %>
<%= form.input :name, :label => "Full Name" %>
<%= form.input :manager_id, :as => :radio %>
<%= form.input :hired_at, :as => :date, :label => "Date Hired" %>
<%= form.input :phone, :required => false, :hint => "Eg: +1 555 1234" %>
<% end %>
<% end %>
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 |
# File 'lib/formtastic.rb', line 80 def input(method, = {}) if .key?(:selected) || .key?(:checked) || .key?(:default) ::ActiveSupport::Deprecation.warn( "The :selected, :checked (and :default) options are deprecated in Formtastic and will be removed from 1.0. " << "Please set default values in your models (using an after_initialize callback) or in your controller set-up. " << "See http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html for more information.", caller) end [:required] = method_required?(method) unless .key?(:required) [:as] ||= default_input_type(method, ) html_class = [ [:as], ([:required] ? :required : :optional) ] html_class << 'error' if @object && @object.respond_to?(:errors) && !@object.errors[method.to_sym].blank? wrapper_html = .delete(:wrapper_html) || {} wrapper_html[:id] ||= generate_html_id(method) wrapper_html[:class] = (html_class << wrapper_html[:class]).flatten.compact.join(' ') if [:input_html] && [:input_html][:id] [:label_html] ||= {} [:label_html][:for] ||= [:input_html][:id] end input_parts = @@inline_order.dup input_parts = input_parts - [:errors, :hints] if [:as] == :hidden list_item_content = input_parts.map do |type| send(:"inline_#{type}_for", method, ) end.compact.join("\n") return template.content_tag(:li, Formtastic::Util.html_safe(list_item_content), wrapper_html) end |
#inputs(*args, &block) ⇒ Object Also known as: input_field_set
Creates an input fieldset and ol tag wrapping for use around a set of inputs. 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 fields. These two examples are functionally equivalent:
# With a block:
<% semantic_form_for @post do |form| %>
<% form.inputs do %>
<%= form.input :title %>
<%= form.input :body %>
<% end %>
<% end %>
# With a list of fields:
<% semantic_form_for @post do |form| %>
<%= form.inputs :title, :body %>
<% end %>
# Output:
<form ...>
<fieldset class="inputs">
<ol>
<li class="string">...</li>
<li class="text">...</li>
</ol>
</fieldset>
</form>
Quick Forms
When called without a block or a field list, an input is rendered for each column in the model’s database table, just like Rails’ scaffolding. You’ll obviously want more control than this in a production application, but it’s a great way to get started, then come back later to customise the form with a field list or a block of inputs. Example:
<% semantic_form_for @post do |form| %>
<%= form.inputs %>
<% end %>
With a few arguments:
<% semantic_form_for @post do |form| %>
<%= form.inputs "Post details", :title, :body %>
<% end %>
Options
All options (with the exception of :name/:title) are passed down to the fieldset as HTML attributes (id, class, style, etc). If provided, the :name/:title option is passed into a legend tag inside the fieldset.
# With a block:
<% semantic_form_for @post do |form| %>
<% form.inputs :name => "Create a new post", :style => "border:1px;" do %>
...
<% end %>
<% end %>
# With a list (the options must come after the field list):
<% semantic_form_for @post do |form| %>
<%= form.inputs :title, :body, :name => "Create a new post", :style => "border:1px;" %>
<% end %>
# ...or the equivalent:
<% semantic_form_for @post do |form| %>
<%= form.inputs "Create a new post", :title, :body, :style => "border:1px;" %>
<% end %>
It’s basically a fieldset!
Instead of hard-coding fieldsets & legends into your form to logically group related fields, use inputs:
<% semantic_form_for @post do |f| %>
<% f.inputs do %>
<%= f.input :title %>
<%= f.input :body %>
<% end %>
<% f.inputs :name => "Advanced", :id => "advanced" do %>
<%= f.input :created_at %>
<%= f.input :user_id, :label => "Author" %>
<% end %>
<% f.inputs "Extra" do %>
<%= f.input :update_at %>
<% end %>
<% end %>
# Output:
<form ...>
<fieldset class="inputs">
<ol>
<li class="string">...</li>
<li class="text">...</li>
</ol>
</fieldset>
<fieldset class="inputs" id="advanced">
<legend><span>Advanced</span></legend>
<ol>
<li class="datetime">...</li>
<li class="select">...</li>
</ol>
</fieldset>
<fieldset class="inputs">
<legend><span>Extra</span></legend>
<ol>
<li class="datetime">...</li>
</ol>
</fieldset>
</form>
Nested attributes
As in Rails, you can use semantic_fields_for to nest attributes:
<% semantic_form_for @post do |form| %>
<%= form.inputs :title, :body %>
<% form.semantic_fields_for :author, @bob do |author_form| %>
<% author_form.inputs do %>
<%= author_form.input :first_name, :required => false %>
<%= author_form.input :last_name %>
<% end %>
<% end %>
<% end %>
But this does not look formtastic! This is equivalent:
<% semantic_form_for @post do |form| %>
<%= form.inputs :title, :body %>
<% form.inputs :for => [ :author, @bob ] do |author_form| %>
<%= author_form.input :first_name, :required => false %>
<%= author_form.input :last_name %>
<% end %>
<% end %>
And if you don’t need to give options to your input call, you could do it in just one line:
<% semantic_form_for @post do |form| %>
<%= form.inputs :title, :body %>
<%= form.inputs :first_name, :last_name, :for => @bob %>
<% end %>
Just remember that calling inputs generates a new fieldset to wrap your inputs. If you have two separate models, but, semantically, on the page they are part of the same fieldset, you should use semantic_fields_for instead (just as you would do with Rails’ form builder).
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 |
# File 'lib/formtastic.rb', line 259 def inputs(*args, &block) title = field_set_title_from_args(*args) = args. [:class] ||= "inputs" [:name] = title if [:for] # Nested form inputs_for_nested_attributes(*(args << ), &block) elsif block_given? field_set_and_list_wrapping(*(args << ), &block) else if @object && args.empty? args = self.association_columns(:belongs_to) args += self.content_columns args -= RESERVED_COLUMNS args.compact! end legend = args.shift if args.first.is_a?(::String) contents = args.collect { |method| input(method.to_sym) } args.unshift(legend) if legend.present? field_set_and_list_wrapping(*((args << ) << contents)) end end |
#label(method, options_or_text = nil, options = nil) ⇒ Object
Generates the label for the input. It also accepts the same arguments as Rails label method. It has three options that are not supported by Rails label method:
-
:required - Appends an abbr tag if :required is true
-
:label - An alternative form to give the label content. Whenever label
is false, a blank string is returned.
-
:input_name - Gives the input to match for. This is needed when you want to
to call f.label :authors but it should match :author_ids.
Examples
f.label :title # like in rails, except that it searches the label on I18n API too
f.label :title, "Your post title"
f.label :title, :label => "Your post title" # Added for formtastic API
f.label :title, :required => true # Returns <label>Title<abbr title="required">*</abbr></label>
399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 |
# File 'lib/formtastic.rb', line 399 def label(method, =nil, =nil) if .is_a?(Hash) return "" if [:label] == false = text = .delete(:label) else text = ||= {} end text = localized_string(method, text, :label) || humanized_attribute_name(method) text += required_or_optional_string(.delete(:required)) text = Formtastic::Util.html_safe(text) # special case for boolean (checkbox) labels, which have a nested input if .key?(:label_prefix_for_nested_input) text = .delete(:label_prefix_for_nested_input) + text end input_name = .delete(:input_name) || method super(input_name, text, ) end |
#semantic_errors(*args) ⇒ Object
Generates error messages for given method names and for base. You can pass a hash with html options that will be added to ul tag
Examples
f.semantic_errors # This will show only errors on base
f.semantic_errors :state # This will show errors on base and state
f.semantic_errors :state, :class => "awesome" # errors will be rendered in ul.awesome
454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 |
# File 'lib/formtastic.rb', line 454 def semantic_errors(*args) = args. 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? [:class] ||= "errors" template.content_tag(:ul, ) do Formtastic::Util.html_safe(full_errors.map { |error| template.content_tag(:li, Formtastic::Util.html_safe(error)) }.join) end end |
#semantic_fields_for(record_or_name_or_array, *args, &block) ⇒ Object
A thin wrapper around #fields_for to set :builder => Formtastic::SemanticFormBuilder for nesting forms:
# Example:
<% semantic_form_for @post do |post| %>
<% post.semantic_fields_for :author do |author| %>
<% author.inputs :name %>
<% end %>
<% end %>
# Output:
<form ...>
<fieldset class="inputs">
<ol>
<li class="string"><input type='text' name='post[author][name]' id='post_author_name' /></li>
</ol>
</fieldset>
</form>
373 374 375 376 377 378 |
# File 'lib/formtastic.rb', line 373 def semantic_fields_for(record_or_name_or_array, *args, &block) opts = args. opts[:builder] ||= Formtastic::SemanticFormHelper.builder args.push(opts) fields_for(record_or_name_or_array, *args, &block) end |