RespondForHelper

A rails helper for responding request format.

Dependencies

ruby 2.3+
rails 5.0+

Installation

Add this line to your application's Gemfile:

gem 'respond_for_helper'

Then execute:

$ bundle

Usage

This gem adds respond_for method in your controller. respond_for performs default behaviour such as template rendering or redirection for each action. Default behaviour is like respond_to which is generated by scaffold of rails. For example:

class ItemsController < ActionController::Base
  def create
    @item = Item.new
    @item.save
    respond_for @item
  end
end

this action is succeeded when @item.errors is empty, otherwise this action is failed. This action returns html, json or any data corresponding to the request format.

respond_for allows some options as follows:

# Always success without checking error existence.
respond_for @item, success: true

# Enable or disable some formats.
respond_for @item, html: true, json: true, any: false

respond_for also supports short options for html format:

# Specify redirect location when succeeded.
# The value should be one of symbol (action name), string or proc.
respond_for @item, location: :index
respond_for @item, location: url_for(@item)
respond_for @item, location: -> { url_for(@item) }

# Specify template when failed.
# The value should be one of symbol (action name) or proc.
respond_for @item, failure_template: :some_template
respond_for @item, failure_template: -> { :some_template }

# Specify notice message when succeeded by symbol, string or proc.
respond_for @item, notice: :notice
respond_for @item, notice: 'Create was succceeded'
respond_for @item, notice: -> { 'Create was succceeded' }

# Specify alert message when failed by symbol, string or proc.
respond_for @item, alert: :alert
respond_for @item, alert: 'Create was failed'
respond_for @item, alert: -> { 'Create was failed' }

respond_for also supports block like respond_to:

# Use full-customized behaviour.
respond_for @item do |format, respond|
  if respond.success?
    format.html { redirect_to action: :index }
  else
    format.html { redirect_to action: :show }
  end
end

You can use callbacks like after_success or after_failure in the block. Note that the callbacks are called after running respond behaviours like render or redirect:

# Set callbacks running after respond.
respond_for @item do |format, respond|
  respond.after_success { puts "succeeded" }
  respond.after_failure { puts "failed" }
end

Flash message

Flash message will be generated for each action automatically. Its format is customizable by i18n translations. Translations below shows the default english message:

en:
  respond_for:
    format: "%{message}%{success_num}%{failure_num}%{timestamp}"
    message:
      defaults:
        default:
          notice: Succeeded
          alert: Failed
        create:
          notice: Successfully created
          alert: Failed to create
        update:
          notice: Successfully updated
          alert: Failed to update
        destroy:
          notice: Successfully destroyed
          alert: Failed to destroy
    success_num: " (%{value} succeeded)"
    failure_num: " (%{value} failed)"
    timestamp: " (%{value})"

If you want to generate a flash message in your own context, you can use respond_for_message as follows:

class ItemsController < ActionController::Base
  def create
    respond_for_message :notice
    #=> Successfully created (2021-01-01 10:00)

    respond_for_message :notice, success_num: 10
    #=> Successfully created (10 succeeded) (2021-01-01 10:00)

    respond_for_message :notice, action_name: :update
    #=> Successfully updated (2021-01-01 10:00)

    respond_for_message :alert
    #=> Failed to create (2021-01-01 10:00)
  end
end

Controller-specific message

You can also define controller-specific message:

en:
  respond_for:
    message:
      items:
        create:
          notice: Item was Successfully created
          alert: Item was failed to create

Note that items is a path of controller you want to define.

Configurations

default behaviours

You can customize default behaviours for each action. For example:

RespondForHelper.configure do |config|
  config.behaviours = {
    html: {
      index: { render: :index },
      show: { render: :show },
      create: {
        success: { redirect: :index, status: :see_other, flash: :notice },
        failure: { render: :new, status: :unprocessable_entity, flash: :alert }
      }
    }
  }
end

html is a request format. index, show, create is a action name of your controller. success is used when current action is succeeded, while failure is used when current action is failed. All of them contains default behaviours which are defined as render, redirect or head.

Controller-specific behaviours

You can also customize controller-specific behaviours:

class ItemsController < ActionController::Base
  self.respond_for_config = {
    html: {
      create: {
        success: { redirect: :show }
      }
    }
  }
end

The way of setting is same as config.behaviours.

Format processors

You can also set your own format processors as you like:

RespondForHelper.configure do |config|
  config.formats = [:html, :json, :any]
  config.formatters = {
    html: RespondForHelper::Formats::Html,
    json: RespondForHelper::Formats::Json,
    any: RespondForHelper::Formats::Any
  }
end

Format processors should be extended by RespondForHelper::Formats::Base.

You can also set your own flash message generators:

RespondForHelper.configure do |config|
  config.flasher = RespondForHelper::Flashes::Timestamp
end

Flash message generators should be extended by RespondForHelper::Flashes::Base.

Contributing

Bug reports and pull requests are welcome at https://github.com/kanety/respond_for_helper.

License

The gem is available as open source under the terms of the MIT License.