# RespondForHelper

A rails helper for responding request format.

## Dependencies

* ruby 2.3+
* rails 5.0+

## Installation

Add this line to your application's Gemfile:

```ruby
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:

```ruby
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 or json corresponding to the request format.

`respond_for` allows some options as follows:

```ruby
# Specify redirect location when succeeded.
# The value should be one of string, symbol (action name) or proc.
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

# Specify notice message when succeeded.
respond_for @item, notice: 'Create was succceeded'

# Specify alert message when failed.
respond_for @item, alert: 'Create was failed'

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

# Block is called when succeeded.
respond_for @item do
  puts "succeeded"
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:

```yaml
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:

```ruby
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:

```yaml
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:

```ruby
RespondForHelper.configure do |config|
  config.default_behaviours = {
    template: {},
    location: {},
    failure_template: { create: :new, update: :edit, destroy: :show, _default: :show },
    failure_location: { _default: :show }
  }
end
```

`template` and `location` is used when current action is succeeded,
while `failure_template` and `failure_location` is used when current action is failed.
All of them contains action name mapping:
the key of mapping is a current action and the value of mapping is a next action after succeeded or failed.
`_default` is a common action which is applied to all of actions which have not specific mapping.

#### Controller-specific behaviours

You can also customize controller-specific behaviours:

```ruby
class ItemsController < ActionController::Base
  self.respond_for_behaviours = {
    location: { _default: :show }
  }
end
```

The way of setting is same as `config.default_behaviours`.

#### Format processors

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

```ruby
RespondForHelper.configure do |config|
  config.formats = {
    html: RespondForHelper::Formats::Html,
    json: RespondForHelper::Formats::Json
  }
  config.flash = RespondForHelper::Flashes::Timestamp
end
```

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

You can also set your own flash message generators:

```ruby
RespondForHelper.configure do |config|
  config.flash = 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](http://opensource.org/licenses/MIT).