Ominous¶ ↑

This engine adds warnings to a rails application.

Add to your gemfile:

'gem ominous'

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

mount Ominous::Engine => "/ominous"

Also ensure that you have root path defined in your routes:

root to: 'some_controller#index'

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

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

rake ominous:install:migrations

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.

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.

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)

Warnings contain a title and description. Closers contain a message and link_text. These elements will be displayed within the warning message. See:

app/views/ominous/warnings/_list.html.erb

Default text will appear if these fields are empty. These defaults being the minimum needed to generate a usable warning message.

If warning#title is blank, a humanized version of the warning name will be displayed.

If closer.link_text is blank, the closer’s link text will be constructed from the closure_method.

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.