https://github.com/comfy/comfy-bootstrap-form
Rails form builder for Bootstrap 4 markup that actually works!
https://github.com/comfy/comfy-bootstrap-form
bootstrap rails rails-form-builder ruby
Last synced: 7 months ago
JSON representation
Rails form builder for Bootstrap 4 markup that actually works!
- Host: GitHub
- URL: https://github.com/comfy/comfy-bootstrap-form
- Owner: comfy
- License: mit
- Created: 2018-01-22T19:30:02.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2023-12-07T19:28:56.000Z (almost 2 years ago)
- Last Synced: 2025-03-30T18:09:48.928Z (8 months ago)
- Topics: bootstrap, rails, rails-form-builder, ruby
- Language: Ruby
- Homepage:
- Size: 2.47 MB
- Stars: 80
- Watchers: 7
- Forks: 12
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- fucking-awesome-ruby - ComfyBootstrapForm - Rails form builder that makes it easy to create forms with Bootstrap 4 markup (Form Builder)
README
# ComfyBootstrapForm
**bootstrap_form** is a Rails form builder that makes it super easy to integrate
[Bootstrap 4](https://getbootstrap.com/) forms into your Rails application.
[](http://rubygems.org/gems/comfy_bootstrap_form)
[](http://rubygems.org/gems/comfy_bootstrap_form)
[](https://travis-ci.org/comfy/comfy-bootstrap-form)
[](https://coveralls.io/r/comfy/comfy-bootstrap-form?branch=master)
[](https://gitter.im/comfy/comfortable-mexican-sofa)
## Requirements
- Rails 5.0+
- Bootstrap 4.0.0+
## Installation
Add gem to your Gemfile and run `bundle install`
```ruby
gem "comfy_bootstrap_form", "~> 4.0.0"
```
## Usage
Here's a simple example:
```erb
<%= bootstrap_form_with model: @user do |form| %>
<%= form.email_field :email %>
<%= form.password_field :password %>
<%= form.check_box :remember_me %>
<%= form.submit "Log In" %>
<% end %>
```
This will generate HTML similar to this:
```html
Email
Password
Remember me
```
## Form helpers
#### bootstrap_form_with
Wrapper around `form_with` helper that's available in Rails 5.1 and above.
Here's an example:
```erb
<%= bootstrap_form_with model: @person, scope: :user do |form| %>
<%= form.email_field :email %>
<%= form.submit %>
<% end %>
```
#### bootstrap_form_for
Wrapper around `form_for` helper that's available in all Rails 5 versions.
Here's an example:
```erb
<%= bootstrap_form_for @person, as: :user do |form| %>
<%= form.email_field :email %>
<%= form.submit %>
<% end %>
```
## Supported form field helpers
This gem wraps most of the default form field helpers. Here's the current list:
```
color_field file_field phone_field text_field
date_field month_field range_field time_field
datetime_field number_field search_field url_field
email_field password_field text_area week_field
date_select time_select datetime_select
check_box radio_button rich_text_area
collection_select
collection_check_boxes
collection_radio_buttons
```
#### Radio Buttons and Checkboxes
To render collection of radio buttons or checkboxes we use the same helper that
comes with Rails. The only difference is that it doesn't accept a block. This
gem takes care of rendering of labels and inputs for you.
```erb
<%= form.collection_radio_buttons :choices, ["red", "green", "blue"], :to_s, :to_s %>
<%= form.collection_check_boxes :choices, Choices.all, :id, :label %>
```
You may choose to render inputs inline:
```erb
<%= form.collection_check_boxes :choices, Choices.all, :id, :label, bootstrap: { check_inline: true } %>
```
#### Submit
Submit button is automatically wrapped with Bootstrap markup. Here's how it looks:
```erb
<%= form.submit %>
<%= form.submit "Submit" %>
<%= form.primary %>
```
You can also pass in a block of content that will be appended next to the button:
```erb
<%= form.submit "Save" do %>
Cancel
<% end %>
```
#### Plaintext helper
There's an additional field helper that render read-only plain text values:
```erb
<%= form.plaintext :value %>
```
#### Form Group
When you need to wrap arbitrary content in markup that renders correctly in
Bootstrap form:
```erb
<%= form.form_group do %>
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
<% end %>
```
If you need to add a label:
```erb
<%= form.form_group bootstrap: { label: {text: "Lorem" }} do %>
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
<% end %>
```
## Bootstrap options
Here's a list of all possible bootstrap options you can pass via `:bootstrap`
option that can be attached to the `bootstrap_form_with` and any field helpers
inside of it:
```
layout: "vertical"
label_col_class: "col-sm-2"
control_col_class: "col-sm-10"
label_align_class: "text-sm-right"
inline_margin_class: "mr-sm-2"
label: {}
append: nil
prepend: nil
help: nil
error: nil
check_inline: false
custom_control: true
```
Options applied on the form level will apply to all field helpers. Options
on field helpers will override form-level options. For example, here's a form
where all labels are hidden:
```erb
<%= bootstrap_form_with model: @user, bootstrap: { label: { hide: true }} do |form| %>
<%= form.email_field :email %>
<%= form.text_field :username %>
<% end %>
```
Here's an example of a form where one field uses different label alignment:
```erb
<%= bootstrap_form_with model: @user do |form| %>
<%= form.email_field :email, bootstrap: { label_align_class: "text-sm-left" } %>
<%= form.text_field :username %>
<% end %>
```
#### Horizontal Form
By default form is rendered as a stack. Labels are above inputs, and inputs
take up 100% of the width. You can change form layout to `horizontal` to put
labels and corresponding inputs side by side:
```erb
<%= bootstrap_form_with model: @user, bootstrap: { layout: "horizontal" } do |form| %>
<%= form.email_field :email %>
<% end %>
```
#### Inline Form
You may choose to render form elements in one line. Please note that this layout
won't render all form elements. Things like errors messages won't show up right.
```erb
<%= bootstrap_form_with url: "/search", bootstrap: { layout: "inline" } do |form| %>
<%= form.text_field :query %>
<%= form.submit "Search" %>
<% end %>
```
#### Label
You can change label generated by Rails to something else:
```erb
<%= form.text_field :value, bootstrap: { label: "Custom Label" } %>
<%= form.text_field :value, bootstrap: { label: {text: "Custom Label" }} %>
```
You may hide label completely (it's still there for screen readers):
```erb
<%= form.text_field :value, bootstrap: { label: { hide: true }} %>
```
Custom CSS class on the label tag? Sure:
```erb
<%= form.text_field :value, bootstrap: { label: { class: "custom-label" }} %>
```
#### Help Text
You may attach help text for pretty much any field type:
```erb
<%= form.text_field :value, bootstrap: { help: "Short helpful message" } %>
```
#### Append and Prepend
Bootstrap allows prepending and appending content to fields via `input-group`.
Here's how this looks:
```erb
<%= form.text_field :value, bootstrap: { prepend: "$", append: "%" } %>
```
If you want to use something like a button, or other html content do this:
```erb
<% button_html = capture do %>
Don't Press
<% end %>
<%= form.text_field :value, bootstrap: { append: { html: button_html }} %>
```
#### Custom Forms
Bootstrap can replace native browser form elements with custom ones for checkboxes,
radio buttons and file input field. Enabled by default. Example usage:
```erb
<%= form.file_field :photo, bootstrap: { custom_control: true } %>
<%= form.collection_radio_buttons :choice, %w[yes no], :to_s, :to_s, bootstrap: { custom_control: true } %>
```
#### Disabling Bootstrap
You may completely disable bootstrap and use default form builder by passing
`disabled: true` option. For example:
```erb
<%= form.text_field :username, bootstrap: { disabled: true } %>
```
### Gotchas
- In Rails 5.1 `form_with` does not generate ids for inputs. If you want them
you'll need to override this method: [actionview/lib/action_view/helpers/form_helper.rb#L745](https://github.com/rails/rails/blob/bdc581616b760d1e2be3795c6f0f3ab4b1e125a5/actionview/lib/action_view/helpers/form_helper.rb#L745)
- For inline radio buttons and check boxes you need to add custom css for error
messages show up. See: [twbs/bootstrap/issues/25540](https://github.com/twbs/bootstrap/issues/25540)
For now adding `.invalid-feeback { display: block }` will work.
## Demo App
Feel free to take a look at the [Demo App](/demo) to see how everything renders.
Specifically see [form.html.erb](/demo/app/views/bootstrap/form.html.erb) template
for all kinds of different form configurations you can have.
---
Copyright 2018-20 Oleg Khabarov, Released under the [MIT License](LICENSE.md)