README.markdown

Unobtrusive flash messages for Rails

Ever got tired of pages that can't be cached because they contain flash messages?

Ever got tired of writing custom code to handle flash messages passed in AJAX responses?

Here comes the solution.

unobtrusive_flash takes your flash messages for the backend and automagically passes them to the frontend via HTTP cookies. This works with both regular page loads, jQuery AJAX requests, and turbolinks (from v3), does not tamper with the page body and requires about 3 extra lines of code in your app - how's that for unobtrusive?

You can pass up to 4K of text into flash this way, and you don't need to worry about cookie size since they are cleared immediately upon rendering.

Tested in all major browsers, including Internet Explorer 8 and later.

Requirements

• Rails >=3 (Latest versions of 3.2, 4.0, 4.1, 4.2, and 5 are automatically tested)
• jQuery (Latest versions of jQuery 1, 2 and 3 are automatically tested)

Usage

1. Add the unobtrusive_flash gem to your Gemfile.

   gem 'unobtrusive_flash', '>=3'

2. Add the following to the controllers that generate flash messages (or better, to the ApplicationController):

   after_action :prepare_unobtrusive_flash

   Flash messages are HTML escaped in the same manner as regular Rails view code: if a message is not html_safe, it is escaped, otherwise not. This lets you use helpers such as link_to in your messages.

3. Include require unobtrusive_flash in your application.js.

4. Delete flash rendering code from your views, if there was any.

5. You have three options to render flash messages on the frontend:

Option 1: For Bootstrap projects

Also require unobtrusive_flash_bootstrap in your application.js. This file contains flash message UI based on the Bootstrap alert component.

Either declare a .unobtrusive-flash-container element somewhere on the page to contain the alerts, or Unobtrusive flash will choose the first .container or .container-fluid element on the page, or fall back to the body.

If you want the flash messages to disappear automatically, set this in your Javascript:

UnobtrusiveFlash.flashOptions["timeout"] = 2000; // milliseconds

You can config the resulting mapping classes like this:

UnobtrusiveFlash.flashOptions.mapping.notice = "success";

Option 2: For non-Bootstrap projects

Also require unobtrusive_flash_ui in your application.js and require unobtrusive_flash_ui in your application.css. These files contain a no-frills flash message UI that works out of the box.

If you want the flash messages to disappear automatically, set this in your Javascript:

UnobtrusiveFlash.flashOptions["timeout"] = 2000; // milliseconds

Option 3: Roll your own

Unobtrusive Flash triggers jQuery events when flash is received. If you want to integrate it with your own UI, implement and bind a handler:

flashHandler = function(e, params) {
  alert(
    "Received flash message " + params.message + " with type " + params.type
  );
};

$(window).bind("rails:flash", flashHandler);

Using UnobtrusiveFlash with a frontend framework that doesn't use jQuery for AJAX

Call UnobtrusiveFlash.showFlashFromCookies() in your Javascript after a completed request.

Bonus: show 'flash messages' from the front-end

Both Bootstrap and non-Bootstrap versions contain a function to display flash messages:

// Shown for 5 seconds (default)
UnobtrusiveFlash.showFlashMessage("Hello World", { type: "notice" });
// Shown forever
UnobtrusiveFlash.showFlashMessage("Error", { type: "error", timeout: 0 });

Using custom flash keys

By default, Unobtrusive Flash only displays a limited set of flash types (see UnobtrusiveFlash::ControllerMixin#unobtrusive_flash_keys). This is because some libraries use flash to keep data that is not directed at the user; for example, Devise uses a boolean flash[:timedout]. If you use other keys to store messages, override unobtrusive_flash_keys in your controller:

class ApplicationController
  def unobtrusive_flash_keys
    super << :success
  end
end

Issue with certain "hosted domains"

There are certain domains that are considered "public" or "hosting" and specifically don't share cookies across subdomains. An example is herokuapp.com - a cookie set for yourapp.herokuapp.com will not be applied for myapp.herokuapp.com. This breaks the logic of unobtrusive_flash which is tuned for regular domains that could have internal subdomains.

In this case, you should explicitly specify your domain:

class ApplicationController
  def unobtrusive_flash_domain
    request.host # last resort is hardcoding the domain here
  end
end

Running tests

This plugin's test suite includes a full set of integration tests for various versions of Rails. To run them:

bundle install
appraisal install
appraisal rake spec

The same tests are ran on Travis CI against multiple versions of Ruby and jQuery.

---

© 2010-2016 Leonid Shevtsov and contributors, released under the MIT license