Module: Ramaze::Helper::BananaForm

Defined in:
lib/ext/ramaze/helper/banana_form.rb

Overview

Banana Form Helper

Overview

The banana form heloer is derived from the ramaze standard BlueForm helper.

Features:

  • provide additional parameters for form element css class styling

  • provide form error management that includes an error summary and css style changing on impacted fields, very much like the rails view helper

Styling

All the BananaForm::Form methods accept the following parameters for css styling :

  • class : class for the input element

  • class_label : class for the input label

  • class_error : class for input in case of validation errors on that field

  • class_label_error : class for the label if any validation errors occur on the related input field

Error Handling

The errors are declared in the very same way that in the BlueFrom, however the form behavior is different.

If errors have been declared, prior to form construction, the form helper class will check the existing errors and corelate them with input fields.

The labels and fields linked to the errors will have their class attribute changed in order to apply some highlighting or any other presentation layer that would provide the user with hints.

Further, the form will have a div section that will display an error summary very similar to the one provided by rails view helper.

All styles, including the summary related can be overridden by providing the appropriate parameters in the Ramaze::Helper::BananaForm::Form methods.

Please note that the gem and helper don’t provide any of the css styles and that we consider that this is part of your job.

Declaring Errors

The errors are declared before the form is constructed using the following module methods :

  • Ramaze::Helper::BananaForm.form_error : adds a new error with name and message

  • Ramaze::Helper::BananaForm.form_errors_from_model : adds all the errors contained in a ‘model’ class instance (i.e providing errors hash)

Please note that those are the same methods than in BlueForm, and that the source code is unchanged.

Error Summary Default Properties

The summary will be inserted as a div element before the fieldset tag.

Default id and class are set to the form_error_summary value. If you want to see something fancy in a minimum laps of type just copy the rails errorExplanation style to form_error_summary and include it in your form page.

Default Field and Labels styles

The form construction is managed by the Ramaze::Helper::BananaForm::Form class, so please check the documentation of the class methods in order to find out the default styles.

Examples

There are a bunch of examples in the specs located under the test directory of the gem. It is probably your best way into BananaForm …

Defined Under Namespace

Classes: Form

Instance Method Summary collapse

Instance Method Details

#form(options = {}, &block) ⇒ Object

Constructs a new form

Constructs a form with options and an optional block that will provide content

Example :

form(:method => :post, :action => :create, :name => ‘user’ ) do |f|

f.legend('User Details')
f.input_text 'Username', :username, @user.username
f.input_submit 'Create New User'

end

Note :

In a templating engine, you need to do this with an assignement statement. For instance with Erubis it would look like this :

<%=

form(:method => :post, :action => :create, :name => 'user' ) do |f|
  ...
end

%>



105
106
107
108
109
 
# File 'lib/ext/ramaze/helper/banana_form.rb', line 105

def form(options = {}, &block)
  form = Form.new(options)
  form.build(form_errors, &block)
  form
end

#form_error(name, message) ⇒ Object

Adds an error to be managed by the form helper

Uses flash placeholder is flash is available, creates an empty hash if not.

Errors are stored as key/values of the hash.



118
119
120
121
122
123
124
125
 
# File 'lib/ext/ramaze/helper/banana_form.rb', line 118

def form_error(name, message)
  if respond_to?(:flash)
    old = flash[:form_errors] || {}
    flash[:form_errors] = old.merge(name.to_s => message.to_s)
  else
    form_errors[name.to_s] = message.to_s
  end
end

#form_errors ⇒ Object

Returns the error hash

Code inherited from Ramaze::Helper::BlueForm seems to return the used error hash.



131
132
133
134
135
136
137
 
# File 'lib/ext/ramaze/helper/banana_form.rb', line 131

def form_errors
  if respond_to?(:flash)
    flash[:form_errors] ||= {}
  else
    @form_errors ||= {}
  end
end

#form_errors_from_model(obj) ⇒ Object

Adds errors contained in a model instance

The method assumes that the object reference you’re passing as argument responds to a method named errors that return a Hash of errors

It iterates over errors and call the form_error method to insert each error



146
147
148
149
150
 
# File 'lib/ext/ramaze/helper/banana_form.rb', line 146

def form_errors_from_model(obj)
  obj.errors.each do |key, value|
    form_error(key.to_s, value.first % key)
  end
end