Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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: 3 days ago
JSON representation

Rails form builder for Bootstrap 4 markup that actually works!

Awesome Lists containing this project

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.

[![Gem Version](https://img.shields.io/gem/v/comfy_bootstrap_form.svg?style=flat)](http://rubygems.org/gems/comfy_bootstrap_form)
[![Gem Downloads](https://img.shields.io/gem/dt/comfy_bootstrap_form.svg?style=flat)](http://rubygems.org/gems/comfy_bootstrap_form)
[![Build Status](https://img.shields.io/travis/comfy/comfy-bootstrap-form.svg?style=flat)](https://travis-ci.org/comfy/comfy-bootstrap-form)
[![Coverage Status](https://img.shields.io/coveralls/comfy/comfy-bootstrap-form.svg?style=flat)](https://coveralls.io/r/comfy/comfy-bootstrap-form?branch=master)
[![Gitter](https://badges.gitter.im/comfy/comfortable-mexican-sofa.svg)](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.

![Demo Preview](/demo/preview.png)

---

Copyright 2018-20 Oleg Khabarov, Released under the [MIT License](LICENSE.md)