hopewise / announcements

Easy way to display short announcement messages in your views.

announcements

The Announcements gem provides an easy way to publish short messages in your views, which the user can then hide permanently. It was influenced by the gem paul_revere by thoughtbot, but unlike paul_revere, announcements doesn't use partials (instead, there is a single helper method which you can customise) and is a bit more flexible (you have an additional 'type' attribute by default). Announcements can also output text in a twitter-bootstrap style format (see below).

Quick start

1. Requirements: rails >= 3.1.0 and jquery-rails
2. Add gem 'announcements' to your Gemfile and run bundle
3. Run rails g announcements:install
4. Use <%= announce Announcement.newest %> in your views to display the latest announcement
5. Create your first announcement in rails c by simply creating a new Announcement record, like Announcement.create(:body => 'This is my first announcement!')
6. You're done! You can now add some styling and have a look at the customization options below.

Styling

By default, the announcement text and hide message text are wrapped in a div called "info" (if you want to customise that, see the Customisation section below). You can use the following css in your application.css file to start:

.info {
	background: #D5EDF8;
	color: #205791;
	padding: 0.8em;
	margin-bottom: 1em;
	border: 2px solid #92CAE4;
}

.hide_announcement {
	cursor: pointer;
	float: right;
}

Customization

The default HTML output of the announce helper is

<div class="info">
	My announcement!
	<span class="hide_announcement" data-announcementid="1">hide message</span>
</div>

The default div class is info. You can customise it like that:

<%= announce Announcement.newest, :div_class => "mydiv" %>

You can also change the "hide message" text:

<%= announce Announcement.newest, :hide_message => "×" %>

The output from the helper is marked as html_safe, so you can have links or add more formatting in the announcement text itself.

For Twitter Bootstrap users

A new option has been added to announcements to display alerts in the twitter-bootstrap style through the following usage:

<%= announce Announcement.newest, :format => "bootstrap" %>

You can also change the "alert heading" text (twitter bootstrap option only):

<%= announce Announcement.newest, {:format => "bootstrap", :alert_heading => "Achtung!"} %>

Be sure to use one of the twitter-bootstrap gems.

How it works

The gem creates an Announcement model with a few class methods like Announcement.newest. The Announcement model has a body:text (the actual announcement text) and a type:string (which you can use for different types of announcements, e.g. public (everyone) and private (only for registered users)). There is also a js file in vendor/assets/javascripts which permanently hides the announcement by creating a cookie (that's when you click on the 'hide message' text).

How to uninstall

There is no uninstaller at this point, but you can simply remove the following files manually:

1. app/models/announcement.rb
2. vendor/assets/javascripts/announcements.js

You also have to remove the //= require announcements line in your app/assets/javascripts/application.js file, and rollback the create_announcements migration.