= Ominous

This engine adds warnings to a rails application.

== Installation

Add to your gemfile:

    'gem ominous'

Add this to your routes to mount the engine within your application:

    mount Ominous::Engine => "/ominous"

Some ominous functionality is provided by JavaScript. To enable this, you
need to add this to your app/assets/javascripts/application.js

    //= require ominous/warnings

== Migrations

Use this command to copy the ominous migrations over to the parent rails app:

    rake ominous:install:migrations

== Warnings

Warnings are the core model used by Ominous.

    warning = Ominous::Warning.create :something_happened

Once a warning has been created, it can triggered with:

    Ominous::Warning.trigger :something_happened

This causes a flag to be set in session, indicating that the associated warning
needs to be displayed.

== Displaying Warnings

To display a warning add this somewhere in the page:

    <%= ominous_warnings %>

This will insert a div of class 'ominous_warnings', containing the warning messages 
(if any have been triggered).

If you wish to use the ominous default styling, add this to your application.scss file:

    *= require ominous/warnings

Alternatively, you can define your own styling.

== Closing a warning

Closers provide links within a warning, that allow a user to handle the warning.
How the link behaves depends upon the closure method associated with the closer.
See app/models/ominous/closer.rb for a list of closure methods and the behaviour
associated with them.

Warnings can have many closers, and closers can be shared across many warnings.
This is achieved through the WarningCloser class. This class acts_as_list, 
so that it can be used to arrange the closers within a warning. To move
a closer within a warning, use this pattern:

    warning.<acts_as_list_method>(closer)

For example:

    warning.move_to_top(closer) 

== Warning text

Warnings contain a title and description. Closers contain a message and a link.
The text used for each needs to be defined in your locale file.

For the something_happened warning used above
the entry needs to look like this:

    en:

      ominous:
        warning:
          something_happened:
            title: Warning
            description: You have triggered a warning.
            closer_one:
              message: This is the first closer
              link: Click here to activate closer_one
            closer_two:
              message: This is the second closer
              link: Click here to activate closer_two


== Managing warnings

This engine does not provide a tool for creating warnings and their associated
closers. It is envisage that warnings and closers will be defined in the 
background app, for example via seeds (see test/dummy). If more flexible 
assignment and management is require, this should be built into the host 
application.