active_element

0.0.13
Light Mode Dark Mode

Forms

An interface for creating forms is provided by active_element.component.form, available in all views.

The Form component delegates to Rails’ form_with so any keyword arguments not processed by ActiveElement can be passed as usual.

Forms in ActiveElement provide a number of features designed to save you time and help you create powerful and flexible forms with minimal effort:

  • Validation errors are automatically rendered for each form element when using ActiveRecord objects or any object that implements #errors, #valid?, etc.
  • Form inputs are inferred from the database column type of each field specified in the fields array.
  • A powerful JSON editor is provided for editing complex JSON objects with user-friendly form elements.
  • A full text search auto-suggest component with a quick and easy setup.
  • Clean and consistent layout.

See the full keyword argument specification for information on the various available options and the Form Fields section for documentation on each individual field type.

Basic Example

subject do
  active_element.component.form model: User.new,
                                fields: [:name, :email, :enabled]
end

it { is_expected.to include '<label for="user_name">' }
<div class="form pb-3" id="form-wrapper-active-element-1f90f21e-aa5c-44af-ad3c-37915209c930">
  <form id="active-element-1f90f21e-aa5c-44af-ad3c-37915209c930" class="user m-3" action="/_users" accept-charset="UTF-8" method="post"><input type="hidden" name="authenticity_token" value="tiuwV2W02eMxnm5n4mYPn-rP8ioE0A2h3PO6BvcW3V4yAmTIyFGbhwMVkO18_Uuf7NXUEH7iBx7l0wX9bj8PkQ" autocomplete="off" />
    <div class="row form-fields mb-3">
      <div class="col-sm-3">
        <label for="user_name">
          Name
        </label>
      </div>
      <div class="col">
        <input class="form-control " tabindex="2" label="Name" type="text" name="user[name]" id="user_name" />
      </div>
    </div>
    <div class="row form-fields mb-3">
      <div class="col-sm-3">
        <label for="user_email">
          Email
          <button type="button"
            style="background: none; border: none; outline: 0; position: absolute;  margin-top: 0.3rem"
            data-bs-toggle="popover"
            data-bs-trigger="focus"
            title="Email"
            data-bs-content="We will use your email address to send your account details.">
            <i class="text-secondary fa-solid fa-circle-info"></i>
          </button>
        </label>
      </div>
      <div class="col">
        <input class="form-control my-email-field-class" tabindex="3" label="Email" description="We will use your email address to send your account details." placeholder="Enter your email address, e.g. user@example.com" type="email" name="user[email]" id="user_email" />
      </div>
    </div>
    <div class="row form-fields mb-3">
      <div class="col-sm-3">
        <label for="user_enabled">
          Enabled
        </label>
      </div>
      <div class="col">
        <input name="user[enabled]" type="hidden" value="0" autocomplete="off" /><input tabindex="4" class="form-check-input " label="Enabled" type="checkbox" value="1" name="user[enabled]" id="user_enabled" />
      </div>
    </div>
    <div class="form-group">
      <input type="submit" name="" value="Create User" class="btn btn-success" data-disable-with="Create User" />
      <a data-form-input-type="clear" class="btn btn-primary  btn-secondary ms-2" title="Clear Form" href="#">
        <span class="text-nowrap">
          <span class="button-title">Clear Form</span>
        </span>
      </a>
    </div>
  </form>
</div>
Clear Form

Options

Forms receive the following keyword arguments. Any other arguments are passed to the underlying form_with call used to generate the form.

Keyword Description
fields An Array of Symbol. Specifies the fields to render in the form. If a model keyword is used then this enables automatic type inference, otherwise the default field type is text_field. Pass an array of two-element arrays to specify a specific field type, e.g. fields: [[:name, :text_field]]. See Form Fields documentation for available field types.
item Optionally pass a Hash instead of using model. This is useful for e.g. creating a form for generating search parameters.
submit Either a String specifying the text to display on the submit button, or a hash with the following optional keys: [:label, :position]. Set position to one of [:top, :bottom, :both], e.g.: submit: { label: 'Create', position: :top }.
title A String specifying a title text to display above the form.
destroy A boolean specifying whether to display a “Delete” button above the form. This is only useful for forms editing an existing ActiveRecord object, e.g. in an edit.html.erb view. Defaults to false.
action A String that overrides the default action (path the form is submitted to). If this value is not passed, the value is automatically inferred from the current controller path and action: #new and #create actions to e.g. /users, #edit and #update actions submit to e.g. /users/:id/edit.
method A String that overrides the default method (typically PATCH or POST). Like action, this is automatically inferred from the current controller path and action.
modal A boolean specifying whether to provide a button that opens the form as a modal. Defaults to false.
columns An Integer specifying how many columns to use when rending form inputs. Defaults to 1.

For typical Rails RESTful routing patterns using ActiveRecord objects you will usually only need to specify model and fields.

Documentation generated by rspec-documentation