ViewPartialFormBuilder

Construct <form> elements and their fields by combining ActionView::Helpers::FormBuilder with Rails View Partials.

Usage

Building the Form

First, render a <form> element with form_with the necessary fields:

<%# app/views/users/new.html.erb %>

<%= form_with(model: user) do |form| %>
  <%= form.label(:name) %>
  <%= form.text_field(:name, class: "text-field", required: true) %>

  <%= form.label(:email) %>
  <%= form.email_field(:email, class: "text-field text-field--large", required: true) %>

  <%= form.label(:password) %>
  <%= form.password_field(:email, class: "text-field",  required: true) %>

  <%= form.button(class: "button button--primary") %>
<% end %>

Declaring the Fields' View Partials

Next, declare view partials that correspond to the FormBuilder helper method you'd like to have more control over:

<%# app/views/application/form_builder/_text_field.html.erb %>

<input
  type="text"
  name="<%= form.object_name %>[<%= method %>]"
  class="text-field"
<% options.each do |attribute, value| %>
  <%= attribute %>="<%= value %>"
<% end %>
>

<%# app/views/application/form_builder/_email_field.html.erb %>

<input
  type="email"
  name="<%= form.object_name %>[<%= method %>]"
  class="text-field text-field--large"
<% options.each do |attribute, value| %>
  <%= attribute %>="<%= value %>"
<% end %>
>

<%# app/views/application/form_builder/_button.html.erb %>

<button
  class="button button--primary"
<% options.each do |attribute, value| %>
  <%= attribute %>="<%= value %>"
<% end %>
>
  <%= value %>
</button>

You'll have local access to the FormBuilder instance as the template-local form variable. You can mix and match between declaring HTML elements, and generating HTML through Rails' helpers:

<%# app/views/application/form_builder/_email_field.html.erb %>

<div class="email-field-wrapper">
  <%= form.email_field(method, required: true, **options)) %>
</div>

<%# app/views/application/form_builder/_button.html.erb %>

<div class="button-wrapper">
  <%= form.button(value, options, &block) %>
</div>

Templates with calls to FormBuilder#fields and FormBuilder::fields_for will yield instances of ViewPartialFormBuilder as block arguments.

With the exception of fields and fields_for, view partials for all other FormBuilder field methods can be declared.

When a partial for a helper method is not declared, ViewPartialFormBuilder will fall back to the default helper method's behavior.

Arguments

Every view partial has access to the arguments it was invoked with. For example, the FormBuilder#button accepts two arguments: method and value. Arguments are made available as partial-local variables (along with key-value pairs in the local_assigns).

In addition, each view partial receives:

• form - a reference to the instance of ViewPartialFormBuilder, which is a descendant of ActionView::Helpers::FormBuilder

• block - the block if the helper method was passed one. Forward it along to field helpers as &block.

Handling DOMTokenList attributes

An HTML element's class attribute is treated by browsers as a DOMTokenList:

set of space-separated tokens. Such a set is returned by Element.classList, ... HTMLAnchorElement.relList...

It is indexed beginning with 0 as with JavaScript Array objects. DOMTokenList is always case-sensitive.

When rendering a field's DOMTokenList-backed attributes (like class or "data-controller" when specifying StimulusJS controllers), transforming and combining singular String instances into lists of token can be very useful.

These optional attributes are available through the options or html_options partial-local variables. Their name will depend on the partial's corresponding ActionView::Helpers::FormBuilder interface.

To "merge" attributes together, you can combine Ruby's String interpolation and Hash#delete:

  <%# app/views/users/new.html.erb %>
<%= form_with(model: post) do |form| %>
  <%= form.text_field(:name, class: "text-field--modifier") %>
<% end %>

<# app/views/application/form_builder/_text_field.html.erb %>

<%= form.text_field(
  method,
  class: "text-field #{options.delete(:class)}",
  **options
) %>

The resulting HTML <input> element will merge have its class attribute set to a list containing both sets of ERB-side class: values:

<input type="text" name="post[name]" class="text-field text-field--modifier">

Rendering the Fields

The fields' view partial files behave like any other: their contents will be used to populate the original call-site.

To opt-out of view partial rendering for a field, first call #default on the block-local form variable:

<%# app/views/users/form_builder/_email_field.html.erb %>

<%= form.default.email_field(method, options) %>

When passing a model: or scope: to calls to form_with, a pluralized version of the FormBuilder's object name will be prepended to the look up path.

For example, when calling form_with(model: User.new), a partial declared in app/views/users/form_builder/ would take precedent over a partial declared in app/views/application/form_builder/.

<%# app/views/users/form_builder/_password_field.html.erb %>

<div class="password-field-wrapper">
  <%= form.password_field(method, options) %>
</div>

If you'd like to render a specific partial for a field, make sure that you pass along the form: (along with any other partial-local variables) as part of the render call's locals: option:

<%# app/views/users/new.html.erb %>

<%= form_with(model: User.new) do |form| %>
  <%= render("emails/my_special_email_field", {
    form: form,
    method: :email,
    options: { class: "user-email" },
  ) %>
<% end %>

<%# app/views/emails/_my_special_email_field.html.erb %>

<%= form.email_field(
  method,
  class: "my-special-email #{options.delete(:class)},
  **options
) %>

Composing partials

Layering partials on top of one another can be useful to share foundational styles and configuration across your fields. For instance, consider an administrative interface that shares styles with a consumer facing site, but has additional bells and whistles.

Declare the consumer facing inputs (in this example, <input type="search">):

<%# app/views/application/form_builder/_search_field.html.erb %>

<%= form.search_field(
  method,
  class: "
    search-field
    #{options.delete(:class)}
  ",
  "data-controller": "
    input->search#executeQuery
    #{options.delete(:"data-controller")}
  ",
  **options
) %>

Then, declare the administrative interface's inputs, in terms of overriding the foundation built by the more general definitions:

<%# app/views/admin/application/form_builder/_search_field.html.erb %>

<%= form.search_field(
  method,
  class: "
    search-field--admin
    #{options.delete(:class}
  ",
  "data-controller": "
    focus->admin-search#clearResults
    #{options.delete(:"data-controller")}
  ",
) %>

The rendered admin/application/form_builder/search_field partial combines options and arguments from both partials:

<input
  type="search"
  class="
    search-field
    search-field--admin
  "
  data-controller="
    input->search#executeQuery
    focus->admin-search#clearResults
  "
>

When constructing fields within a form_with(model: ...) block, partials will use the model: instance's tableize-d model name to resolve partials.

For example, posts/form_builder/_text_field.html.erb will be resolved ahead of form_builder/_text_field.html.erb:

<%# app/views/posts/form_builder/_text_field.html.erb %>

<%= form.text_field(method, class: "post-text #{options.delete(:class)}", **options) %>

<%# app/views/application/form_builder/_text_field.html.erb %>

<%= form.text_field(method, class: "text #{options.delete(:class)}", **options) %>

The rendered posts/form_builder/text_field partial could combine options and arguments from both partials:

<input type="text" class="post-text text">

Models declared within modules will be delimited with /. For example, Special::Post instances would first resolve partials within the app/views/special/posts/form_builder directory, before falling back to app/views/application/form_builder.

Configuration

View partials lookup and resolution will be scoped to the app/views/application/form_builder directory.

To override this destination to another directory (for example, app/views/fields, or app/views/users/fields), set ViewPartialFormBuilder.view_partial_directory:

# config/initializers/view_partial_form_builder.rb
ViewPartialFormBuilder.view_partial_directory = "fields"

Installation

Add this line to your application's Gemfile:

gem 'view_partial_form_builder'

And then execute:

$ bundle

Contributing

See CONTRIBUTING.md.

License

The gem is available as open source under the terms of the MIT License.