Module: Forme

Included in:
Sequel::Plugins::Forme::SequelInput
Defined in:
lib/forme.rb,
lib/forme/sinatra.rb,
lib/forme/version.rb,
lib/forme/rails.rb

Overview

Forme is designed to make creating HTML forms easier. Flexibility and simplicity are primary objectives. The basic usage involves creating a Forme::Form instance, and calling input and tag methods to return html strings for widgets, but it could also be used for serializing to other formats, or even as a DSL for a GUI application.

In order to be flexible, Forme stores tags in abstract form until output is requested. There are two separate abstract forms that Forme uses. One is Forme::Input, and the other is Forme::Tag. Forme::Input is a high level abstract form, while Forme::Tag is a low level abstract form.

The difference between Forme::Input and Forme::Tag is that Forme::Tag directly represents the underlying html tag, containing a type, optional attributes, and children, while the Forme::Input is more abstract and attempts to be user friendly. For example, these both compile by default to the same select tag:

f.input(:select, :options=>[['foo', 1]])
# or
f.tag(:select, {}, [f.tag(:option, {:value=>1}, ['foo'])])

The processing of high level Forme::Inputs into raw html data is broken down to the following steps (called transformers):

  1. Formatter: converts a Forme::Input instance into a Forme::Tag instance (or array of them).

  2. ErrorHandler: If the Forme::Input instance has a error, takes the formatted tag and marks it as having the error.

  3. Labeler: If the Forme::Input instance has a label, takes the formatted output and labels it.

  4. Wrapper: Takes the output of the labeler (or formatter if no label), and wraps it in another tag (or just returns it directly).

  5. Serializer: converts a Forme::Tag instance into a string.

Technically, only the Serializer is necessary. The input and tag methods return Input and Tag objects. These objects both have to_s defined to call the appropriate Serializer with themselves. The Serializer calls the appropriate Formatter if it encounters an Input instance, and attempts to serialize the output of that (which is usually a Tag instance). It is up to the Formatter to call the Labeler and/or ErrorHandler (if necessary) and the Wrapper.

There is also an InputsWrapper transformer, that is called by Forme::Form#inputs. It’s used to wrap up a group of related options (in a fieldset by default).

The Forme::Form object takes the 6 transformers as options (:formatter, :labeler, :error_handler, :wrapper, :inputs_wrapper, and :serializer), all of which should be objects responding to call (so you can use Procs) or be symbols registered with the library using Forme.register_transformer:

Forme.register_transformer(:wrapper, :p){|t| t.tag(:p, {}, t)}

Most of the transformers can be overridden on a per instance basis by passing the appopriate option to input or inputs:

f.input(:name, :wrapper=>:p)

Defined Under Namespace

Modules: Rails, Raw, Serialized, Sinatra Classes: Error, ErrorHandler, Form, Formatter, Input, InputsWrapper, Labeler, Serializer, Tag

Constant Summary collapse

TRANSFORMER_TYPES =

Array of all supported transformer types.

[:formatter, :serializer, :wrapper, :error_handler, :labeler, :inputs_wrapper]
CONFIGURATIONS =

Hash storing all configurations. Configurations are groups of related transformers, so that you can specify a single :config option when creating a Form and have all of the transformers set from that.

{:default=>{}}
TRANSFORMERS =

Main hash storing the registered transformers. Maps transformer type symbols to subhashes containing the registered transformers for that type. Those subhashes should have symbol keys and values that are either classes or objects that respond to call.

{}
VERSION =

Version constant, use Forme.version instead.

'0.9.1'.freeze

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.default_config ⇒ Object

Set the default configuration to use if none is explicitly specified (default: :default).



75
76
77
 
# File 'lib/forme.rb', line 75

def default_config
  @default_config
end

Class Method Details

.attr_classes(attr, *classes) ⇒ Object

Update the :class entry in the attr hash with the given classes.



125
126
127
 
# File 'lib/forme.rb', line 125

def self.attr_classes(attr, *classes)
  attr[:class] = merge_classes(attr[:class], *classes)
end

.form(*a, &block) ⇒ Object

Call Forme::Form.form with the given arguments and block.



120
121
122
 
# File 'lib/forme.rb', line 120

def self.form(*a, &block)
  Form.form(*a, &block)
end

.merge_classes(*classes) ⇒ Object

Return a string that includes all given class strings



130
131
132
 
# File 'lib/forme.rb', line 130

def self.merge_classes(*classes)
  classes.compact.join(' ')
end

.register_config(type, hash) ⇒ Object

Register a new configuration. Type is the configuration name symbol, and hash maps transformer type symbols to transformer name symbols.



113
114
115
 
# File 'lib/forme.rb', line 113

def self.register_config(type, hash)
  CONFIGURATIONS[type] = CONFIGURATIONS[hash.fetch(:base, :default)].merge(hash)
end

.register_transformer(type, sym, obj = nil, &block) ⇒ Object

Register a new transformer with this library. Arguments:

type

Transformer type symbol

sym

Transformer name symbol

obj/block

Transformer to associate with this symbol. Should provide either obj or block, but not both. If obj is given, should be either a Class instance or it should respond to call. If a Class instance is given, instances of that class should respond to call, and a new instance of that class should be used for each transformation.

Raises:



105
106
107
108
109
 
# File 'lib/forme.rb', line 105

def self.register_transformer(type, sym, obj=nil, &block)
  raise Error, "Not a valid transformer type" unless TRANSFORMERS.has_key?(type)
  raise Error, "Must provide either block or obj, not both" if obj && block
  TRANSFORMERS[type][sym] = obj||block
end

.version ⇒ Object

Returns the version as a frozen string (e.g. ‘0.1.0’)



6
7
8
 
# File 'lib/forme/version.rb', line 6

def self.version
  VERSION
end