Field Partials
Bullet Train includes a collection of view partials that are intended to DRY-up as much redundant presentation logic as possible for different types of form fields without taking on a third-party dependency like Formtastic.
Responsibilities
These form field partials standardize and centralize the following behavior across all form fields that use them:
- Apply theme styling and classes.
- Display any error messages for a specific field inline under the field itself.
- Display a stylized asterisk next to the label of fields that are known to be required.
- Any labels, placeholder values, and help text are defined in a standardized way in the model's localization Yaml file.
- For fields presenting a static list of options (e.g. a list of buttons or a select field) the options can be defined in the localization Yaml file.
It's a simple set of responsibilities, but putting them all together in one place cleans up a lot of form view code. One of the most compelling features of this "field partials" approach is that they're just HTML in ERB templates using standard Rails form field helpers within the standard Rails form_with
method. That means there are no "last mile" issues if you need to customize the markup being generated. There's no library to fork or classes to override.
The Complete Package
Each field partial can optionally include whichever of the following are required to fully support it:
- Controller assignment helper to be used alongside Strong Parameters to convert whatever is submitted in the form to the appropriate ActiveRecord attribute value.
- Turbo-compatible JavaScript invocation of any third-party library that helps support the field partial.
- Theme-compatible styling to ensure any third-party libraries "fit in".
- Capybara testing helper to ensure it's easy to inject values into a field partial in headless browser tests.
Basic Usage
The form field partials are designed to be a 1:1 match for the native Rails form field helpers developers are already used to using. For example, consider the following basic Rails form field helper invocation:
<%= form.text_field :text_field_value, autofocus: true %>
Using the field partials, the same field would be implemented as follows:
<%= render 'shared/fields/text_field', form: form, method: :text_field_value, options: {autofocus: true} %>
At first blush it might look like a more verbose invocation, but that doesn't take into account that the first vanilla Rails example doesn't handle the field label or any other related functionality.
Breaking down the invocation:
text_field
matches the name of the native Rails form field helper we want to invoke.- The
form
option passes a reference to the form object the field will exist within. - The
method
option specifies which attribute of the model the field represents, in the same way as the first parameter of the basic Railstext_field
helper. - The
options
option is basically a passthrough, allowing you to specify options which will be passed directly to the underlying Rails form field helper.
The 1:1 relationship between these field partials and their underlying Rails form helpers is an important design decision. For example, the way options
is passed through to native Rails form field helpers means that experienced Rails developers will still be able to leverage what they remember about using Rails, while those of us who don't readily remember all the various options of those helpers can make use of the standard Rails documentation and the great wealth of Rails code examples available online and still take advantage of these field partials. That means the amount of documentation we need to maintain for these field partials is strictly for those features that are in addition to what Rails provides by default.
Individual field partials might have additional options available based on the underlying Rails form field helper. Links to the documentation for individual form field partials are listed at the end of this page.
options
vs. html_options
Most of the native form helpers use options
to define html attributes like so:
def text_field(object, method, options = {})
...
end
However, the super_select
partial uses html_options
to define them. This is the same as the native Rails select form helper. Each field partial has its own set of arguments that can be passed to it depending on the underlying form helper, so please refer to the field partial options documentation for more details.
options
vs. other_options
Because Bullet Train field partials have more responsibilities than the underlying Rails form field helpers, there are also additional options for things like hiding labels, displaying specific error messages, and more. For these options, we pass them separately as other_options
. This keeps them separate from the options in options
that will be passed directly to the underlying Rails form field helper.
For example, to suppress a label on any field, we can use the hide_label
option like so:
<%= render 'shared/fields/text_field', form: form, method: :text_field_value, other_options: {hide_label: true} %>
Please refer to the field partial options documentation for more details.
other_options
Options
Globally-Available Key | Value Type | Description |
---|---|---|
help |
string | Display a specific help string. |
error |
string | Display a specific error string. |
hide_label |
boolean | Hide the field label. |
required |
boolean | Display an asterisk by the field label to indicate the field is required. |
required
: through presence validation vs. options: {required: true}
vs. other_options:{required: true}
By default, where there's a presence validation on the model attribute, we add an asterisk to indicate the field is required. For fields without a presence validation, you have options to pass the :required
detail:
other_options: {required: true}
adds the asterisk to the field manually.options: {required: true}
adds asterisk but also triggers client-side validation via therequired
attribute.
Since client-side validations vary from browser to browser, we recommend relying on server-side validation for most forms, and thus mostly using other_options[:required]
.
Reducing Repetition
When you're including multiple fields, you can DRY up redundant settings (e.g. form: form
) like so:
<% with_field_settings form: form do %>
<%= render 'shared/fields/text_field', method: :text_field_value, options: {autofocus: true} %>
<%= render 'shared/fields/buttons', method: :button_value %>
<%= render 'shared/fields/image', method: :cloudinary_image_value %>
<% end %>
Field partials that integrate with third-party service providers
image
makes it trivial to upload photos and videos to Cloudinary and store their resulting Cloudinary ID as an attribute of the model backing the form. To enable this field partial, sign up for Cloudinary and copy the "Cloudinary URL" they provide you with into yourconfig/application.yml
asCLOUDINARY_URL
. If you use our Heroku app.json to provision your production environment, this will happen in that environment automatically.
Yaml Configuration
The localization Yaml file (where you configure label and option values for a field) is automatically generated when you run Super Scaffolding for a model. If you haven't done this yet, the localization Yaml file for Scaffolding::CompletelyConcrete::TangibleThing
serves as a good example. Under en.scaffolding/completely_concrete/tangible_things.fields
you'll see definitions like this:
text_field_value:
name: &text_field_value Text Field Value
label: *text_field_value
heading: *text_field_value
api_title: *text_field_value
api_description: *text_field_value
This might look redundant at first glance, as you can see that by default the same label ("Text Field Value") is being used for both the form field label (label
) and the heading (heading
) of the show view and table view, and in API api_title
and api_descriptions
are used for documentation purposes. It's also used when the field is referred to in a validation error message. However, having these three values defined separately gives us the flexibility of defining much more user-friendly labels in the context of a form field. In my own applications, I'll frequently configure these form field labels to be much more verbose questions (in an attempt to improve the UX), but still use the shorter label as a column header on the table view and the show view:
text_field_value:
name: &text_field_value Text Field Value
label: "What should the value of this text field be?"
heading: *text_field_value
api_title: *text_field_value
api_description: *text_field_value
You can also configure some placeholder text (displayed in the field when in an empty state) or some inline help text (to be presented to users under the form field) like so:
text_field_value:
name: &text_field_value Text Field Value
label: "What should the value of this text field be?"
heading: *text_field_value
api_title: *text_field_value
api_description: *text_field_value
placeholder: "Type your response here"
help: "The value can be anything you want it to be!"
Certain form field partials like buttons
and super_select
can also have their selectable options configured in this Yaml file. See their respective documentation for details, as usage varies slightly.
Available Field Partials
Field Partial | Data Type | Multiple Values? | Assignment Helpers | JavaScript Library | Description |
---|---|---|---|---|---|
address_field |
Address |
Adds a block of address fields. On change, its country super-select auto-updates the state/province/region super-select and postal/zip code field label. | |||
boolean |
boolean |
assign_boolean |
|||
buttons |
string |
Optionally | assign_checkboxes |
||
image |
string or attachment * |
||||
color_picker |
string |
pickr | |||
date_and_time_field |
datetime |
Date Range Picker | |||
date_field |
date |
Date Range Picker | |||
email_field |
string |
||||
emoji_field |
string |
Emoji Mart | A front-end library which allows users to browse and select emojis with ease. | ||
file_field |
attachment |
Active Storage | |||
options |
string |
Optionally | assign_checkboxes |
||
password_field |
string |
||||
phone_field |
string |
International Telephone Input | Ensures telephone numbers are in a format that can be used by providers like Twilio. | ||
super_select |
string |
Optionally | assign_select_options |
Select2 | Provides powerful option search, AJAX search, and multi-select functionality. |
text_area |
text |
||||
text_field |
string |
||||
number_field |
integer |
||||
trix_editor |
text |
Trix | Basic HTML-powered formatting features and support for at-mentions amongst team members. |
- The data type for
image
fields will vary based on whether you're using Cloudinary or ActiveStorage. For Cloudinary you should usestring
, and for ActiveStorage you should useattachment
.
A Note On Data Types
When creating a multiple
option attribute, Bullet Train generates these values as a jsonb
.
rails generate super_scaffold Project Team multiple_buttons:buttons{multiple}
This will run the following rails command.
rails generate model Project team:references multiple_buttons:jsonb
date
and date_and_time
Formating After Super Scaffolding a date
or date_and_time
field, you can pass a format for the object like so:
<%= render 'shared/attributes/date', attribute: date_object, format: :short %>
Please refer to the Ruby on Rails documentation for more information.
Dynamic Forms and Dependent Fields
To dynamically update your forms on field changes, Bullet Train introduces two new concepts:
- Dependent Fields Pattern
- Dependent Fields Frame
These concepts are currently used by the address_field
to dynamically update the State / Province / Region field on Country change, as well as the label for the Postal Code field.
Read more about Dynamic Forms and Dependent Fields