bootstrap_flash_messages
version 1.0.2
Robin Brouwer
Bootstrap alerts and Rails flash messages combined in one easy-to-use gem.
Installation
You can use this gem by putting the following inside your Gemfile:
gem "bootstrap_flash_messages", "~> 1.0.1"
When you're using Bootstrap 2, you can use version 0.0.7.
Now you need flash.en.yml for the flash messages.
rails g bootstrap_flash_messages:locale
And that's it!
Changes
Version 1.0.2 changes (05/08/2015):
- Added :fade_in.
Version 1.0.1 changes (02/08/2015):
- Made 'info' the default class.
Version 1.0.0 changes (31/01/2014):
- Added Boostrap 3 support.
- Added default locales for the flash messages.
- Removed the 'convert_newlines' option and added 'simple_format'.
- Added option to set flash values directly inside 'flash!' and 'flash_now!'.
- Changed the documentation.
Version 0.0.7 changes (26/01/2013):
- Added alert_class_mapping (documentation below).
Version 0.0.6 changes (27/09/2012):
- Added pull request #5 by protolif. This adds the :fade option.
Version 0.0.5 changes (24/09/2012):
- Added HTML escape option for flash_messages helper (:html).
- Also added option to convert new-lines to br-tags (:convert_newlines).
Version 0.0.4 changes (03/09/2012):
- Namespaced Controllers can be accessed by nesting your locales.
# Old
"admin/products":
...
# New:
admin:
products:
...
Version 0.0.3 changes (14/08/2012):
- Added interpolation to the flash messages
Version 0.0.2 changes (10/08/2012):
- Changed the 'x' in close to & t i m e s ;
Version 0.0.1 changes (08/08/2012):
- Changed redirect_to method
- Added flash! and flash_now! methods
- Added flash_messages helper
- Made a gem out of it
Usage
You need Bootstrap 3 for the styling and close button. You can still use it without Bootstrap, but you need to style it yourself. This gem uses the Bootstrap alerts.
If you're customizing Bootstrap, make sure to grab the "Alert" and "Component Animations" (the latter one is optional, unless you want the fade-out animation on close).
All flash messages are defined inside config/locales/flash.en.yml. They are nested like this:
en:
flash_messages:
controller_name:
action_name:
success: "It worked!"
info: "There's something you need to know..."
warning: "You should watch out now."
error: "Oh no! Something went wrong."
You have four keys:
:success
:info
:warning
:error
It is also possible to add default locales globally or per action:
en:
flash_messages:
defaults:
success: "It really worked!"
create:
success: "Created successfully!"
When you've defined the messages it's very easy to call them inside your Controller.
class PostsController
def create
@post = Post.new(params[:post])
if @post.save
redirect_to(@post, :flash => :success)
else
flash_now!(:error)
render("new")
end
end
end
You can use the :flash parameter inside the redirect_to method (note: this gem changes the redirect_to method!) to set the flash messages. You only need to pass the corresponding key and the gem will automatically set flash[:success] to t("flash_messages.posts.create.success"). The :flash parameter also accepts an Array.
redirect_to(@post, :flash => [:success, :info])
You can still use a Hash to use the default redirect_to behavior.
redirect_to(:root, :flash => { :error => I18n.t("flash_messages.authorize_admin") })
When you don't want to use the redirect_to method to set the flash messages, you can use the flash! method.
flash!(:success, :info)
redirect_to(@post)
When you need to use flash.now you can use the flash_now! method.
flash_now!(:error, :warning)
You use flash_now! in combination with rendering a view instead of redirecting.
You can also pass options to flash! and flash_now! to set the flash values directly.
flash!(:error => I18n.t("flash_messages.authorize_admin"))
flash_now!(:error => I18n.t("flash_messages.authorize_admin"))
Now's the time to show these messages to the user. Inside the layout (or any other view), add the following:
<div id="flash_messages"><%= flash_messages %></div>
And that's it! To change the flash messages inside a .js.erb file, you can do the following:
$("#flash_messages").html("<%= j(flash_messages) %>");
The flash_messages helper shows a simple Bootstrap alert box. If you want to add a close button you can add the :close option.
<%= flash_messages(:close) %>
If you'd like for the flash message to fade out when you click on the close icon, you can pass in the :fade option. This requires :close to work, obviously.
<%= flash_messages(:close, :fade) %>
If you'd like for the flash message to also fade in, you can pass in the :fade_in option.
<%= flash_messages(:close, :fade, :fade_in) %>
# Also add something like this to application.js:
window.setTimeout(function() {
$(".alert").addClass("in");
}, 1000);
# If you didn't add the "Component Animations" to your Bootstrap configuration, add this to application.css:
.alert.fade {
opacity: 0;
-webkit-transition: opacity 0.15s linear;
-moz-transition: opacity 0.15s linear;
-o-transition: opacity 0.15s linear;
transition: opacity 0.15s linear;
}
.alert.fade.in {
opacity: 1;
}
Want a heading? Add :heading. The headings inside flash.en.yml are used for the headings.
<%= flash_messages(:close, :heading) %>
Want to put the heading inside a <h4> tag? Just add :block.
<%= flash_messages(:close, :heading, :block) %>
Need to display HTML inside the flash messages? Use the :html option.
<%= flash_messages(:html) %>
It's also possible to use simple_format on the flash message using the :simple_format option.
<%= flash_messages(:simple_format) %>
And that's it! Have fun. :)
Interpolation
You can use i18n interpolation like this:
redirect_to :root, :flash => [:success, :info], :locals => { :name => @user.name, :email => @user.email }
flash! :success, :info, :locals => { :name => @user.name, :email => @user.email }
flash_now! :success, :info, :locals => { :name => @user.name, :email => @user.email }
Inside flash.en.yml you can do the following:
success: "Welcome, %{name}."
info: "Your e-mail address has been changed to: %{email}."
alert_class_mapping
You can map the keys used inside the flash messages to a different alert class. There are 4 different classes for the alert messages inside bootstrap:
alert-success
alert-info
alert-warning
alert-danger
When you use :notice the alert class is mapped (by default) to alert-success. So it looks like this:
:notice maps to "alert-success"
:success maps to "alert-success"
:info maps to "alert-info"
:warning maps to "alert-warning"
:error maps to "alert-danger"
Changing the mapping is quite easy. Create an initializer (config/initializers/bootstrap_flash_messages.rb) and add the following:
module BootstrapFlashMessages
@alert_class_mapping = {
:notice => :danger,
:success => :success,
:info => :info,
:warning => :warning,
:error => :danger
}
end
Now you can map whatever alert class you want to the different keys.
Why I created this gem
I created the gritter gem and used it in a lot of projects. I started using Bootstrap and really liked the alerts. I loved the way gritter allowed you to set messages and decided to do the same for the Bootstrap alerts. And this is the result!
Copyright
Copyright (C) 2012 Robin Brouwer
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.