Voltron::Flash

Unifying flash and flash.now logic into one single method, while also being able to pass flash messages easily through AJAX requests.

Add this line to your application's Gemfile:

gem 'voltron-flash', '~> 0.1.6'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install voltron-flash

Then run the following to create the voltron.rb initializer (if not exists already) and add the upload config:

$ rails g voltron:flash:install

Also, include the necessary js and css by adding the following to your application.js and application.css respectively

//= require voltron-flash

/*
 *= require voltron-flash
 */

If you want to customize the out-of-the-box functionality or styles, you can copy the assets (javascript/css) to your app assets directory by running:

$ rails g voltron:flash:install:assets

Optionlly, you may copy the flash markup template by running:

$ rails g voltron:flash:install:views

The template will be placed in the <rails_root>/app/views/voltron/flash/ directory.

Voltron Flash is designed to handle flash messages appropriately depending on whether a controller renders or redirects, and whether or not the request is an AJAX request. All the developer needs to do is use the new flash! message.

class UserController < ActionController::Base

  def create
    @user = User.new(user_params)
    
    if @user.save
      flash! notice: 'User created successfully'
      redirect_to user_path(@user)

      # Or, you can still add flashes like so if you want. The old ways still work fine
      redirect_to user_path(@user), notice: 'User created successfully'
    else
      flash! alert: @user.errors.full_messages
      render :new
    end
    
    # ... define other things, like our +user_params+ method
  end

end

I hear you: "What's the point of that? You just made a single method that determines whether to use flash vs. flash.now. That's pretty boring."

Meh, depends on your perspective. But part of what makes this useful is it's ability to pass flash messages back as a part of the AJAX response headers.

Using that same example controller from above, the following code (assuming jQuery) is all that's required to handle the flash messages given an AJAX request to the same create action.

$.ajax({
  url: '/users/create',
  method: 'POST',
  data: {
    authenticity_token: '...'
    first_name: 'Test',
    last_name: 'Example',
    email: '',
    // ...
  }
})

Note that there is nothing in that code that relates specifically to the handling flash messages. That's because that is entirely handled by the Voltron Flash js module (see: Installation, specifically for assets).

Included with the gem is a Voltron module that handles the creation/addition/removal of flash messages. Out of the box there should be little to nothing you need to do with it, as it's fairly flexible in terms of how it can be used already.

The most commonly utilized methods will likely be new and clear, which are used like so:

// Adds several messages at once with optionally defined options
Voltron('Flash/new', {
  notice: 'This is a notice message', // Specify as single message,
  alert: ['This is an alert', 'This too is an alert'] // or an array of messages
}, {
  bind: '#container',
  group: true
});

// To clear all flash messages
Voltron('Flash/clear');
// To clear a specific flash message by fading it out over 1 second
Voltron('Flash/clear', {
  element: '.selector-matching-flash-or-child-element' // Can be css selector, raw DOM element, or jQuery object
}, {
  concealMethod: 'fadeOut',
  concealTime: 1000
});

// The above is functionally equivalent to:

Voltron.getModule('Flash').new({
  notice: 'This is a notice message',
  alert: ['This is an alert', 'This too is an alert']
}, {
  bind: '#container',
  group: true
});

// To clear all flash messages
Voltron.getModule('Flash').clear();
// To clear a specific flash message by fading it out over 1 second
Voltron.getModule('Flash').clear({
  element: '.selector-matching-flash-or-child-element' // Can be css selector, raw DOM element, or jQuery object
}, {
  concealMethod: 'fadeOut',
  concealTime: 1000
});

The following are options that can optionally be defined as the second argument to the module's new or clear methods. Each can also be set as a "default" by calling Voltron('Flash/setConfig', { option: value, ... }) in a module initializer. Useful for reducing the amount of code needed to be written, since you can define things like bind once instead of every time you add a flash message.

Keeping it simple, the Flash module only dispatches one event out of the box. More can be added as needed by modifying voltron-flash.js, but for now:

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Bug reports and pull requests are welcome on GitHub at https://github.com/ehainer/voltron-flash. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

The gem is available as open source under the terms of the GNU General Public License.