Module: Ramaze::Helper::BlueForm

Defined in:
lib/ramaze/helper/blue_form.rb

Overview

Introduction

The BlueForm helper tries to be an even better way to build forms programmatically. By using a simple block you can quickly create all the required elements for your form.

Since November 2010 the BlueForm helper works different. You can now specify an object as the first parameter of the form_for() method. This object will be used to retrieve the values of each field. This means that you can directly pass a database result object to the form and no longer have to manually specify values. However, you can still specify your own values if you want.

Old behaviour:

form_for(:method => :post) do |f|
  f.input_text 'Username', :username, 'Chuck Norris'
end

New behaviour:

# @data is an object that contains an instance variable named "username".
# This variable contains the value "Chuck Norris".
form_for(@data, :method => :post) do |f|
  f.input_text 'Username', :username
end

Form Data

As stated earlier it's possible to pass an object to the form_for() method. What kind of object this is, a database result object or an OpenStruct object doesn't matter as long as the attributes can be accessed outside of the object (this can be done using attr_readers). This makes it extremely easy to directly pass a result object from your favourite ORM. Example:

@data = User[1]

form_for(@data, :method => :post) do |f|
  f.input_text 'Username', :username
end

If you don't want to use an object you can simply set the first parameter to nil.

HTML Output

The form helper uses Gestalt, Ramaze's custom HTML builder that works somewhat like Erector. The output is very minimalistic, elements such as legends and fieldsets have to be added manually. Each combination of a label and input element will be wrapped in <p> tags.

When using the form helper as a block in your templates it's important to remember that the result is returned and not displayed in the browser directly. When using Etanni this would result in something like the following:

#{
  form_for(@result, :method => :post) do |f| do
    f.input_text 'Text label', :textname, 'Chunky bacon!'
  end
}

Examples:


form_for(@data, :method => :post) do |f|
  f.input_text 'Username', :username
end

Defined Under Namespace

Classes: Form

Instance Method Summary (collapse)

Instance Method Details

- (Object) form_error(name, message)

Manually add a new error to the form_errors key in the flash hash. The first parameter is the name of the form field and the second parameter is the custom message.

Parameters:

  • name (String) —

    The name of the form field to which the error belongs.

  • message (String) —

    The custom error message to show.



104
105
106
107
108
109
110
111
 
# File 'lib/ramaze/helper/blue_form.rb', line 104

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

- (Array) form_errors

Returns the hash containing all existing errors and allows other methods to set new errors by using this method as if it were a hash.

Returns:

  • (Array) —

    All form errors.



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

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

- (Object) form_errors_from_model(obj)

Retrieve all the form errors for the specified model and add them to the flash hash.

Parameters:

  • obj (Object) —

    An object of a model that contains form errors.



133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/ramaze/helper/blue_form.rb', line 133

def form_errors_from_model(obj)
  if obj.respond_to?(:errors)
    obj.errors.each do |key, value|
      if value.respond_to?(:first)
        value = value.first
      end

      form_error(key.to_s, value % key)
    end
  end
end

- (Object) form_for(form_values, options = {}, &block)

The form method generates the basic structure of the form. It should be called using a block and it's return value should be manually sent to the browser (since it does not echo the value).

Parameters:

  • form_values (Object) —

    Object containing the values for each form field.

  • options (Hash) (defaults to: {}) —

    Hash containing any additional form attributes such as the method, action, enctype and so on.

  • block (Block) —

    Block containing the elements of the form such as password fields, textareas and so on.



89
90
91
92
93
 
# File 'lib/ramaze/helper/blue_form.rb', line 89

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