Preface

This page contains documentation pertaining to a Ruby Gem that I've created: form_­input_­field. This gem is an extension to Action­View::Hel­per­s::For­m­Hel­per within Ruby on Rails' ActionPack framework. form_­input_­field essentially wraps up functionality of maintaining values for forms to factor cases where a POST fails model validation. It also provides a means to succinctly produce relevant error messages for said failed validations.

Consider a simple form which is primarily defined by an HTML input element and its label:

Consider added functionality which presents a new label informing the user any errors discovered upon POST whilst also maintaining the value the user had previously submitted:

It's important to validate such fields on the server, even if JavaScript is doing this work on the front-end. Within Ruby on Rails, (using HAML), the logic may look like the following:

This gem condenses the above into a more concise set of method calls:

This makes a view much more clean and easier to digest at a glance.

---

This gem was influenced by work done in a collaborative Ruby on Rails project. The goal was to abstract away code related to the front-end as much as possible in an effort to create a coding standard. Details pertaining to why and how can be found within the project writing within this website called Developing DRY Forms.

The source code of this gem is found within its GitHub repository. The primary body of this project page will act as a hub for the documentation found within this repository where the contents of the README file and the CHANGELOG file will be presented in tandem with a checklist of current and future progress.

The location of the gem is on RubyGems.org, located here: https://­ruby­gems.org/­gems/­form_­input_­field

---

Action­View::Hel­per­s::For­m­Hel­per::Form­In­put­Field

Installation

Add this line to your application's Gemfile:

-  gem 'form_input_field' 

And then execute:

-  $ bundle 

Or install it yourself as:

-  $ gem install form_­input_­field 

Usage

This gem places two helper methods into Action­View::Hel­per­s::For­m­Hel­per. These methods are form_input_field and form_error_field.

These methods are described below. Examples of their usage are located in the Examples Section of this document.

form_input_field

form_input_field is an abstraction on the software pattern which encapsulates some input element and its label. Additionally, it has built in functionality which helps ensure the input element's value attribute is filled should the flash hash-map contain the presence of this value.

• Outputs two html tags - a label HTML element pointing to its corresponding input HTML element. The term "input HTML element" here is ambiguous; it's not meant to be taken literally. "Input" in this context is meant to be interpreted as any output produced by the following list of helper functions within Action­View::Hel­per­s::For­m­Hel­per:
  • color_field, date_field, datetime_field, datetime_local_field, email_field, file_field, hidden_field, month_field, number_field, password_field, phone_field, range_field, search_field, telephone_field, text_area, text_field, time_field, url_field, week_field
  • In addition to the above list of Form­Helper method calls, form_­input_­field captures two special cases - check_box and radio_button. These are described later.
• The helper_sym argument describes the relevant helper method to be called. It expects the method name as a symbol. I.e., if one needs a call to text_field, pass :text_field; If one needs a call to password_field, supply a value of :password_field, etc.
• The object_name and method arguments correspond to the equivalently named arguments as described in Action­View::Hel­per­s::For­m­Hel­per.
• The label_text argument expects a string for the associated label of the generated input HTML element described by helper_sym. Supplying a false will instead not produce a label HTML element; an empty string is produced for the label.
• The options argument corresponds to a hash-map representing the set of options to be passed with helper_sym; these are the options to be given to a method call from the above set of helper methods. Esentially a hash-map of html properties and attributes. I.e., {:style => "color:red;"}.
• The label_options argument corresponds to a hash-map representing the set of options to be passed with the call to the label helper method from Action­View::Hel­per­s::For­m­Hel­per. Essentially a hash-map of html properties and attributes to be applied to the label. I.e., {:style => "color:red;"}.
• The value_key argument is a symbol that acts as a key for the flash hash-map that contains the relevant value filled by the controller. If the value associated with said key within flash is a string, then the string will occupy the value attribute for the produced input HTML element. If it is a hash-map, it will then assume that the value given for method is the key to the string within this embedded hash-map. Consider the following example:
  • For a view that contains the following call:  form_­input_­field :person, :name, "Please input a name: " , the controller contains either flash[:values] = params[:user][:name] or flash[:values] = params[:user] when User.new(params[:user][:name]).valid? returns a false.

:check_box helper_sym

When using the value of :check_box for helper_sym, the argument set is as follows:

• The checked_value and unchecked_value arguments correspond to the value sent to the server upon post, dependent whether or not the check box is checked.
• The other arguments are unchanged from their descriptions above.

:radio_button helper_sym

When using the value of :radio_button for helper_sym, the argument set is as follows:

• The tag_value argument corresponds to the value that will be sent to the server upon post, dependent whether or not the radio_button is selected.
• The other arguments are unchanged from their descriptions above.

form_error_field

form_error_field is an abstraction on the software pattern which encapsulates the presentation of a validation error. This produces a label HTML element which points to the originating input field. The text of the label is the error message associated with the failed validation. These errors are typically captured from the model by the controller and then sent to the view where this method call is enacted.

• Outputs a label HTML tag whose textual value is located in the flash-hash map corresponding to error_key. If the value associated with said key is a string, then this string value will be used. If it is a hash-map, it will then assume that the value given for method is the key to the string within this embedded hash-map. Consider the following example:
  • For a view that contains the following call: form_­error_­field :person, :name, the controller contains either flash[:errors] = @user.errors[:name] or flash[:errors] = @user.errors, where @user is defined by User.new(params[:user][:name]) and User.valid? returns a false.
• The label_options argument corresponds to a hash-map representing the set of options to be passed with the call to the label helper function from Action­View::Hel­per­s::For­m­Hel­per. Essentially a hash-map of html properties and attributes. I.e., {:style => "color:red;"}.

Examples

form_input_field

form_error_field:

Finished Work

• Base definition of form_input_field such that its optional keyword arguments can be supplied in any order.
• Base definition of form_error_field such that its optional keyword arguments can be supplied in any order.

Future Work

• A mechanism to set flash key defaults.
• Extend these helpers to be compatible with Action­View::Hel­per­s::Form­Builder.
• Create function wrappers specific to the required Action­View::Hel­per­s::For­m­Hel­per method. I.e., form_text_field(:model, :object_name) which calls form_­input_­field(­:text_field, :model, :object_name)

Other avenues of future work will be listed in the issues section of the repository