How to Deploy & Use plataformatec/simple_form

# Simple Form Deployment & Usage Guide

A comprehensive guide for integrating Simple Form into Rails applications and contributing to the gem.

## 1. Prerequisites

**Runtime Requirements:**
- **Ruby**: 2.7 or higher (3.0+ recommended)
- **Rails**: 6.0 or higher (Simple Form 5.x)
- **Bundler**: 2.0 or higher

**For CSS Framework Integration:**
- Bootstrap 5 assets loaded in your Rails application (optional)
- Zurb Foundation 5 assets (optional)
- `country_select` gem (optional, for country inputs)

## 2. Installation

### Standard Installation

Add to your Rails application's `Gemfile`:

```ruby
gem 'simple_form'

Install the gem:

bundle install

Run the installation generator to create initializers:

rails generate simple_form:install

This creates:

config/initializers/simple_form.rb - Core configuration
config/locales/simple_form.en.yml - I18n translations

Bootstrap 5 Integration

For Bootstrap 5 form styling, run:

rails generate simple_form:install --bootstrap

This generates:

config/initializers/simple_form_bootstrap.rb - Bootstrap-optimized wrappers
Configures mb-3 spacing, is-invalid/is-valid classes, and btn classes

Ensure Bootstrap assets are available in your application (via Webpacker, esbuild, or Sprockets).

Zurb Foundation 5 Integration

rails generate simple_form:install --foundation

Generates config/initializers/simple_form_foundation.rb. Note: Uncomment the hint line in this file to enable hints, as they are disabled by default for Foundation.

Optional Country Select

For :country inputs, add to Gemfile:

gem 'country_select'

Then run bundle install.

3. Configuration

Core Initializer (`config/initializers/simple_form.rb`)

Customize the wrapper behavior:

SimpleForm.setup do |config|
  # Default wrapper
  config.wrappers :default, class: :input,
    hint_class: :field_with_hint, 
    error_class: :field_with_errors, 
    valid_class: :field_without_errors do |b|
    
    b.use :html5
    b.use :placeholder
    b.optional :maxlength
    b.optional :minlength
    b.optional :pattern
    b.optional :min_max
    b.optional :readonly
    b.use :label_input
    b.use :hint, wrap_with: { tag: :span, class: :hint }
    b.use :error, wrap_with: { tag: :span, class: :error }
  end

  # Default configuration
  config.default_wrapper = :default
  config.boolean_style = :nested
  config.button_class = 'btn'
  config.error_notification_tag = :div
  config.error_notification_class = 'error_notification'
end

Wrapper API Customization

Define custom wrappers for specific input types:

config.wrappers :horizontal_form, tag: 'div', class: 'form-group row' do |b|
  b.use :html5
  b.use :placeholder
  b.use :label, class: 'col-sm-3 col-form-label'
  b.wrapper tag: 'div', class: 'col-sm-9' do |ba|
    ba.use :input, class: 'form-control'
    ba.use :error, wrap_with: { tag: 'span', class: 'invalid-feedback' }
    ba.use :hint, wrap_with: { tag: 'small', class: 'form-text text-muted' }
  end
end

I18n Configuration

Structure your config/locales/simple_form.en.yml:

en:
  simple_form:
    labels:
      user:
        username: 'User name'
        password: 'Password'
    hints:
      user:
        username: 'Letters and numbers only'
        password: 'Minimum 8 characters'
    placeholders:
      user:
        email: 'user@example.com'
    error_notification:
      default_message: "Please review the problems below:"

Input Mappings

Override automatic input type detection in simple_form.rb:

# Treat :country fields as strings (if not using country_select gem)
config.input_mappings = { /country/ => :string }

4. Build & Run

Usage in Development

Start your Rails server:

bin/rails server

Basic form implementation in views:

<%= simple_form_for @user do |f| %>
  <%= f.input :username %>
  <%= f.input :email, placeholder: 'user@domain.com' %>
  <%= f.input :password, hint: 'Minimum 8 characters' %>
  <%= f.input :remember_me, as: :boolean, inline_label: 'Keep me logged in' %>
  <%= f.button :submit %>
<% end %>

Available input types mapped from database columns:

:string, :email, :password, :tel, :url, :uuid → StringInput
:text, :hstore, :json, :jsonb → TextInput
:integer, :decimal, :float → NumericInput
:date, :time, :datetime → DateTimeInput
:boolean → BooleanInput
:file → FileInput
:rich_text_area → RichTextAreaInput
:country, :time_zone → PriorityInput

Running Tests (For Contributors)

Clone the repository:

git clone https://github.com/heartcombo/simple_form.git
cd simple_form

Install dependencies:

bundle install

Run the test suite:

bundle exec rake test

5. Deployment

Rails Application Deployment

When deploying a Rails app using Simple Form:

Asset Compilation: Ensure CSS classes defined in initializers match your production asset pipeline:

RAILS_ENV=production bin/rails assets:precompile

Initializers: Verify config/initializers/simple_form*.rb files are committed to version control.
I18n: Ensure translation files are loaded in production:

# config/application.rb
config.i18n.load_path += Dir[Rails.root.join('config', 'locales', '**', '*.{rb,yml}')]

Gem Publication (For Maintainers)

To release a new version:

Update version in lib/simple_form/version.rb
Update CHANGELOG.md
Build and publish:

gem build simple_form.gemspec
gem push simple_form-5.x.x.gem

6. Troubleshooting

Wrapper Divs Not Rendering

Issue: Missing wrapper HTML in production but works in development.

Solution: Check that config.action_view.field_error_proc isn't overriding Simple Form's wrappers. Ensure your initializer loads after Rails initialization:

# config/initializers/simple_form.rb
Rails.application.config.after_initialize do
  # Custom wrapper definitions here if needed
end

Bootstrap Styles Not Applied

Issue: Inputs lack Bootstrap styling classes.

Solution: Verify you ran the Bootstrap generator and check simple_form_bootstrap.rb:

# Ensure these are set
config.input_field_error_class = 'is-invalid'
config.input_field_valid_class = 'is-valid'
config.button_class = 'btn'

Country Input Errors

Issue: undefined method 'country_select' error.

Solution: Add to Gemfile:

gem 'country_select'

Or disable country mapping:

config.input_mappings = { /country/ => :string }

Missing Translations

Issue: Labels showing as "Username" instead of custom text.

Solution: Check locale file structure matches exactly:

en:
  simple_form:
    labels:
      model_name:  # Must match model_name.i18n_key
        attribute_name: 'Label Text'

HTML5 Validation Not Working

Issue: Email/url inputs lack validation attributes.

Solution: Ensure b.use :html5 is enabled in your wrapper and not disabled per-input:

<%= f.input :email, html5: false %>  # Disables for this field

Custom Input Not Loading

Issue: uninitialized constant SimpleForm::Inputs::CustomInput.

Solution: Require custom inputs in the initializer:

# config/initializers/simple_form.rb
Dir[Rails.root.join('lib/components/**/*.rb')].each { |f| require f }

Deprecation Warnings

Issue: wrapper_options argument warnings.

Solution: Update custom input methods:

# Old (deprecated)
def input
  # ...

# New
def input(wrapper_options = nil)
  # ...
end