ruby script/plugin install git://github.com/iain/pizza-form_builder.git

Basic usage
=================

This should be relatively straight forward. A form built with PizzaFormBuilder can define fields for your attributes. Fields contain a label, input field, error message and description. So in most cases it’s nothing more than:

  - form_for @user do |form|
    - form.field :name
    - form.field :email

Every field is by default surrounded with ++ tags and contains a label, an appropriate input element (depending on ActiveRecord), an error message and a description.

Important: The field method contats its output, just like form_for.

The field method also accepts a block. In this block you can add extra html or change settings. There is an important difference between a setting and the rendering of an element.

A setting doesn’t have output, so use the hyphen (-) in HAML to do this. When changing a setting inside the block, you can change the setting of one of the 4 main methods called later on. You can change the type of input box it will generate, for example.

  - form_for @user do |form|
    - form.field :name do |field|
      - field.input = :text_area      # input=() is a setting, not a render!

The 4 render methods that are used are input, error, label and description. These methods will return the HTML, so you’ll need to put an equal sign (=) before it. When it gets called, it won’t render again later on. This can be handy to change the order of things.

  - form_for @user do |form|
    - form.field :name do |field|
      = field.input                   # input() is a render, not a setting!
      = field.label
      = field.error
      = field.description

Also, you can of course add regular HTML in this block too. You can change the order and which methods are used. So if don’t use error message next to your fields, for example, it’s trivial to turn them off. All configuration is done by overriding helper methods.

All these methods can take arguments, so read on to learn more!

Field render methods
============================

Label
-----------

The label is automatically adjusted with an asterisk and the class ‘required’ if the attribute can be nil in the database. Force it by providing the required option. You can also use required_field and optional_field for this.

  - form.field :name, :required => true
  - form.required_field :name
  - form.optional_field :name

Input
------------

The input render method looks at the specified object to determine what kind of input box to render. This works only with ActiveRecord though. Strings are input fields, texts are textareas, dates are date_selects, etc.

You can override the field types in several interesting ways.

  - form.field :name, :input => :text_area
  - form.field :name do |field|
    - field.input = :text_area
  - form.field :name do |field|
    - field.set_input :text_area, :class => "add extra options here"
  - form.field :name do |field|
    = field.input :text_area, :class => "render here"

As you have noticed, the latter is a render method. It doesn’t accept an attribute name, because it already knows it. By default a label gets rendered before the input, but because in this case the render method for input was called, it will appear before it. In the first three examples, the order of elements will remain unchanged.

Any available input type available to the form builder can be used. PizzaFormBuilder supports easy adding fields, so the options are limitless.

Also, when the attribute names contains the "password", it’ll be a password field, so even stuff like this get rendered properly.

Description
========================

A description is automatically called from i18n if available. It will be in the attribute scope, so your locale file would look something like:

  nl:
    activerecord:
      attributes:
        user:
          login: Inlognaam
          password: Wachtwoord
          descriptions:
            login: Lorem
            password: Ipsum

You can change the description on the fly:

  - form.field :name do |field|
    - field.description = "foobar"  # description=() is a setting method
    = field.description "foobar"    # description() is a render method

Error
==============

Error is just a mapping to the common Rails method error_message_on. It is a render method, so output it, if you want it. It takes the same arguments as error_message_on, only without the attribute (the first one), because that is already known.

There is currently no advanced documentation for this plugin.