Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
F

forme

> 编程语言
Open source

HTML forms library for ruby

330 stars0 likes2 views
WebsiteGitHub

About

HTML forms library for ruby

= Forme

Forme is a HTML forms library for ruby with the following goals:

  1. Have no external dependencies
  2. Have a simple API
  3. Support forms both with and without related objects
  4. Allow compiling down to different types of output
  5. Integrate easily into web frameworks

= Introduction

Forme is designed to make creating HTML forms easier. Flexibility and ease of use are the primary objectives. Here's a basic example, showing usage without a related object:

Forme.form({:action=>'/foo'}) do |f| f.input(:text, :name=>'bar') f.tag(:fieldset) do f.input(:textarea, :name=>'baz') end f.button('Update') end

This results in the following HTML:

Forme also supports forms that are associated with objects, and has specific support for Sequel::Model objects to allow easily building forms for such objects. The Sequel support handles inputs based on database columns, and automatically handles labels and errors:

Forme.form(Album[1], action: '/foo') do |f| f.input :name f.input :copies_sold end

This results in the following HTML:

Name:
  

Copies Sold:

In addition to integrating with Sequel, Forme also integrates into three separate web frameworks, Roda, Rails, and Sinatra, allowing use of forms inside templates. This is the most common usage of Forme.

One distinct advantage of Forme over other form libraries is the use of an abstract syntax tree internally, allowing the same form code to compile to different HTML with different options. For example, it allows using the exactly same form code to display a form you can modify as well as a read-only view, just by passing a single option when creating the form. For example, with the first example in this section, if you pass the formatter: :readonly option, you get the following HTML instead:

This allows you to reuse the same form code in multiple contexts, which can save considerable development time.

= Installation

gem install forme

= Links

Demo Site :: http://forme-demo.jeremyevans.net RDoc :: http://forme.jeremyevans.net Source :: https://github.com/jeremyevans/forme Discussion Forum :: https://github.com/jeremyevans/forme/discussions Bug Tracker :: https://github.com/jeremyevans/forme/issues

= Direct Instantiation

While not typically done, you can instantiate Forme::Form objects directly and use them:

f = Forme::Form.new f.open(:action=>'/foo', :method=>:post) # '' f.input(:textarea, :value=>'foo', :name=>'bar') # 'foo' f.input(:text, :value=>'foo', :name=>'bar') # '' f.close # ''

With an object, Form#input calls +forme_input+ on the obj with the form, field, and options, which should return a Forme::Input or Forme::Tag instance. Also, in Form#initialize, +forme_config+ is called on object with the form if the object responds to it, allowing customization of the entire form based on the object.

f = Forme::Form.new(obj) f.input(:field) # ''

If the object doesn't respond to +forme_input+, it falls back to creating text fields with the name and id set to the field name and the value set by calling the given method on the object (or using #[] if the object is a hash).

f = Forme::Form.new([:foo]) f.input(:first) # ''

= Forme::Form Creation

+Forme.form+ takes up to 3 arguments, and yields the Forme::Form object to the block (if given). Here are the argument styles that you can use for +Forme.form+.

No args :: Creates a +Form+ object with no options and not associated to an +obj+, and with no attributes in the opening tag. 1 hash arg :: Treated as opening form tag attributes, creating a +Form+ object with no options. 1 non-hash arg :: Treated as the +Form+'s +obj+, with empty options and no attributes in the opening tag. 2 hash args :: First hash is opening attributes, second hash is +Form+ options. 1 non-hash arg, 1-2 hash args :: First argument is +Form+'s obj, second is opening attributes, third if provided is +Form+'s options.

Examples:

No arguments

Forme.form

1 hash argument (attributes)

Forme.form(action: '/foo')

1 non-hash argument (a reference object used when building the form)

Forme.form(Album[1])

2 hash arguments (attributes, and options)

Forme.form({action: '/foo'}, values: params)

1 non-hash argument, 1-2 hash arguments (ref obj, attributes, options)

Forme.form(Album[1], action: '/foo') Forme.form(Album[1], {action: '/foo'}, values: params)

If you want a Forme::Form instance where the reference object is a Hash, then you need to pass the hash object using the :obj option:

Forme.form({action: '/foo'}, obj: {foo: 'bar'})

You can also create Forme::Form objects the normal ruby way using Forme::Form#new. The difference between Forme::Form#new and Forme.form is that Forme.form includes the enclosing tag, where Forme::Form#new does not. Because of this, Forme::Form does not accept a hash of tag attributes, so it has the following API:

No arguments

Forme::Form.new

1 hash argument

Forme::Form.new(values: params)

1 non-hash argument

Forme::Form.new(Album[1])

1 non-hash argument, 1-2 hash arguments

Forme::Form.new(Album[1], values: params)

= Forme::Form Methods

== form

If you create a Form via Forme::Forme#new, you can use the form method to create a form tag:

f = Forme::Form.new f.form(action: '/foo')

This is what Forme.form uses internally to create the ++ tag

== input

This adds an input to the form. If the form has an associated object, and that object responds to +forme_input+, calls forme_input with the argument and options:

f = Forme::Form.new(obj) f.input(:field) # ''

If the form has an associated object, and that object does not respond to +forme_input+, calls the method on the object (or uses [] if the object is a hash), and uses the result as the value for a text input:

f = Forme::Form.new([:foo]) f.input(:first) # ''

If the object does not respond to +forme_input+, you can change the type of the input via the +:type+ option:

f = Forme::Form.new(obj) f.input(:field, :type=>:email) # ''

If the form does not have an associated object, the first argument is used as the input type:

f = Forme::Form.new f.input(:text) # ''

The second argument is an options hash. See below for the supported input types and options.

== tag

This adds a tag to the form. If a block is given, yields to the block, and tags and inputs inside the block are placed inside the tag. The first argument is the type of tag to create, and the second argument if given should be a hash of tag attributes. This allows you to nest inputs inside tags:

Forme.form do |f| f.tag(:span, :class=>"foo") do f.input(:text) end end

Which results in a form similar to the following:

== inputs

This wraps multiple inputs in a tag (it uses the +:inputs_wrapper+ transformer discussed below, so it uses a +fieldset+ by default). You can give the inputs to add as an enumerable argument:

f.inputs([:textarea, [:text, :value=>'a']])

You can also provide a block:

f.inputs([:textarea]) do f.input(:text, :value=>'a') end

Any options given are passed to the +inputs_wrapper+ (so you can use options such as +:legend+ to set a legend for the fieldset), and also to the +with_opts+ method (so you can use options such as +:wrapper+ to modify the default wrapper transformer for inputs inside the block). There is also one option specific to the inputs method:

:nested_inputs_wrapper :: Sets the default inputs_wrapper to use for calls to inputs inside the block. The reason for this option is that +:inputs_wrapper+ option affects the current call to inputs, so if you want to use a different inputs_wrapper for nested calls, you need this option.

== button

This adds a submit input to the form:

f.button

It can be called with a string to provide a value for the button:

f.button('Search')

It can be called with a hash to provide options for the submit input:

f.button(value: 'Search', class: 'btn')

== with_opts

This requires a block, and modifies the Forme::Form's options inside the block, restoring the options when the block returns:

f.input(:text)

f.with_opts(wrapper: :li) do f.input(:text) end

This supports most options you can provide to Forme::Form, but not all.

== with_obj

This uses +with_opts+ to change the Forme::Form object temporarily. It yields the object to the block, and also supports appending to the existing namespaces:

Forme.form([:foo], {action: '/path'}, namespace: 'a') do |f| f.input(:first) # f.with_obj(['foobar'], 'b') do |o| f.input(:first, :size=>o.first.size) # end end

== each_obj

This allows you to provide an object-yielding enumerable. +each_object+ will call +with_obj+ with each object in the enumerable. It yields each object as well as the index of the object in the enumerable, and includes the index in the namespace:

objectlist = [['foobar'], ['good']] Forme.form([:foo], :namespace=>'a') do |f| f.each_obj(objectlist, 'b') do |o, i| f.input(:first, :size=>10+i) end # # end

= Sequel Support

Forme ships with a Sequel plugin (use Sequel::Model.plugin :forme to enable), that makes Sequel::Model instances support the +forme_config+ and +forme_input+ methods and return customized inputs. An additional instance method, +forme_namespace+ can optionally be defined to customize how model classnames are transformed into form classes and input IDs and names. This can be useful if your Sequel::Model classes are nested under a parent namespace. The default namespace uses Sequel::Model#underscore.

module Admin class Albums '/foo') do |f| f.input :name f.input :artist f.input :tags, :as=>:checkbox end

This will create a form similar to:

Name: 
Artist: 
  Elvis Presley
  The Beatles
  The Monkeys

Tags:
   Rock and Roll
   Blues
   Country

For one_to_many and many_to_many associations, you will probably want to use the +association_pks+ plugin that ships with Sequel.

This also supports the pg_array_to_many association type that comes with Sequel's +pg_array_association+ plugin.

association input options:

:as :: For many_to_one associations, set to :radio to use a series of radio buttons instead a select input. For one_to_many, many_to_many, and pg_array_to_many associations, set to :checkbox to use a series of checkboxes instead of a multiple select input. :dataset :: If a Dataset, uses the dataset to retrieve the options. If a Proc or Method, calls the proc or method with the default dataset, and should return a modified dataset to use. :options :: Specify the options to use for the input(s), instead of querying the database. :name_method :: If a String or Symbol, treats it as a method name and calls it on each object returned by the dataset to get the text to use for the option. If not given, tries the following method names in order: :forme_name, :name, :title, :number. If given and not a String or Symbol, a callable object is assumed, and the value is called with each object and should return the text to use for the option.

== subform

The Sequel support includes a method called subform, which can handle nested_attributes:

Forme.form(Album[1], :action=>'/foo') do |f|

f.input :name

f.subform :artist do
  f.input :name
end

f.subform :tracks do
  f.input :number
  f.input :name
end

end

This adds an input for editing the artist's name after the album's inputs, as we

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Ruby

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 18, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言