ominous 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 Rob Nichols
+
+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.

data/README.rdoc

@@ -0,0 +1,97 @@
+= Ominous
+
+This engine adds warnings to a rails application.
+
+== Installation
+
+Add to your gemfile:
+
+    'gem ominous'  # TODO - gem not created yet
+
+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.

data/Rakefile

@@ -0,0 +1,40 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Ominous'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/assets/javascripts/ominous/application.js

@@ -0,0 +1,15 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
+// GO AFTER THE REQUIRES BELOW.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .

data/app/assets/javascripts/ominous/warnings.js

@@ -0,0 +1,33 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.
+
+
+$(function() {  
+
+  $('.ominous_warnings .reveal_hidden').click( function() {
+    $('.ominous_warnings .start_visible').hide();
+    $('.ominous_warnings .start_hidden').show();
+    return false;
+  });
+  
+  $('.ominous_warnings .close_and_dismiss_warning').click( function() {
+    send_data_to_server($(this).attr('href'));
+    $(this).closest('.warning').hide('fade');
+    return false;    
+  });
+  
+
+  function send_data_to_server(url) {
+    $.ajax({
+      type: "PUT",
+      url: url,
+
+      success: function (data) {
+        // console.log(data);
+      },
+      error: function () {
+        // console.log('Error updating');
+      }
+    })
+  }
+})

data/app/assets/stylesheets/ominous/_ominous_colours.scss

@@ -0,0 +1,4 @@
+$white: #FFFFFF;
+$warning: #FF0000;
+
+

data/app/assets/stylesheets/ominous/application.scss

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */

data/app/assets/stylesheets/ominous/warnings.scss

@@ -0,0 +1,41 @@
+@import 'ominous_colours';
+
+.ominous_warnings {
+  .warning {
+    position: absolute;
+    left:15%;
+    top: 100px;
+    margin: auto;
+    width: 70%;
+    z-index: 10000;
+    background-color: $white;
+    border: $warning solid 3px;
+    font-size: 1.2em;
+
+    .heading {
+
+      h2 {
+        background-color: $warning;
+        color: $white;
+        margin: 0;
+      }
+
+    }
+
+    h2, .description, .closers {
+      padding: 5px;
+    }
+
+    .start_hidden {
+      display: none;
+    }
+    
+    .closer {
+      margin: 0 0 1em;
+      p {
+        margin: 0;         
+      }
+    }
+
+  }
+}

data/app/controllers/ominous/application_controller.rb

@@ -0,0 +1,16 @@
+module Ominous
+  class ApplicationController < ActionController::Base
+    
+    protected
+    def check_ominous_warnings
+      Warning.requests.each{|request| session_store << request}
+      Warning.clear_requests
+    end
+    helper_method :check_ominous_warnings
+    
+    def session_store
+      session[:ominous_warnings] ||= []
+    end
+    
+  end
+end

data/app/controllers/ominous/warnings_controller.rb

@@ -0,0 +1,15 @@
+require_dependency "ominous/application_controller"
+
+module Ominous
+  class WarningsController < ApplicationController
+    
+    def dismiss
+      @warning = Warning.find(params[:id])
+      session[:ominous_warnings][@warning.name.to_sym] = :hide
+      render :text => "ominous warning #{@warning.name} set to hidden"
+    end
+    
+
+    
+  end
+end

data/app/helpers/ominous/application_helper.rb

@@ -0,0 +1,39 @@
+module Ominous
+  module ApplicationHelper
+    def ominous_warnings
+      process_ominous_warnings
+      if warnings_to_show?
+        content_tag(
+          'div', 
+          render(
+            :partial => 'ominous/warnings/list',
+            :locals => {:warnings => warning_to_display}
+          ), 
+          :class => 'ominous_warnings')
+      end
+    end
+    
+    def process_ominous_warnings
+      Warning.requests.each do |request| 
+        session_store[request.to_sym] = :show unless session_store[request.to_sym]
+      end
+      Warning.clear_requests
+    end
+    
+    def warnings_to_show?
+      session_store
+      session_store.values.include? :show
+    end
+    
+    def session_store
+      session[:ominous_warnings] ||= {}
+    end
+    
+    def warning_to_display
+      warnings = session_store.keys.collect do |name| 
+        Warning.find_by_name(name) if session_store[name] == :show
+      end
+      return warnings.compact
+    end
+  end
+end

data/app/helpers/ominous/warnings_helper.rb

@@ -0,0 +1,29 @@
+module Ominous
+  module WarningsHelper
+    def classes_for(closer)
+      classes = ['closer']
+      classes << visibility(closer.start_hidden?)
+      classes.join(' ')
+    end
+    
+    def visibility(truth)
+      truth ? 'start_hidden' : 'start_visible'
+    end
+    
+    def closer_link_to(warning, closer)
+      text = t("ominous.warning.#{warning.name}.#{closer.name}.link") 
+      link_class = closer.closure_method
+      url = closer_url(warning, closer)
+      link_to(text, url, :method => :put, :class => link_class)
+    end
+    
+    def closer_url(warning, closer)
+      if closer.closure_method == 'close_and_dismiss_warning'
+        ominous.dismiss_warning_path(warning)
+      else
+        return closer.url
+      end
+    end
+
+  end
+end

data/app/models/ominous/closer.rb

@@ -0,0 +1,19 @@
+module Ominous
+  class Closer < ActiveRecord::Base
+    attr_accessible :name, :url, :closure_method, :start_hidden
+    
+    CLOSURE_METHODS = {
+      :reveal_hidden => 'Hides the current closers and reveals any hidden closers', 
+      :close_and_dismiss_warning => 'Closes the warning message and tells server not to display warning again', 
+      :redirect => 'Link to take user to closer.url without clearing the warning' 
+    }    
+    
+    validates :name, :presence => true
+    validates :closure_method, :inclusion => { :in => CLOSURE_METHODS.keys.collect(&:to_s) }
+    
+    def self.closure_methods
+      CLOSURE_METHODS
+    end
+
+  end
+end

data/app/models/ominous/warning.rb

@@ -0,0 +1,74 @@
+module Ominous
+  class Warning < ActiveRecord::Base
+    attr_accessible :name
+    
+    validates :name, :presence => true
+    
+    has_many(
+      :warning_closers,
+      :uniq => true,
+      :order => :position
+    )
+    
+    has_many(
+      :closers,
+      :through => :warning_closers,
+      :order => :position
+    )
+    
+    def self.trigger(name)
+      unless exists?(:name => name)
+        raise "Attempt to trigger warning failed: #{name} not recognised"
+      end
+      requests << name.to_sym
+    end
+    
+    def self.requests
+      @requests ||= []
+    end
+    
+    def self.clear_requests
+      @requests = []
+    end
+    
+    private
+    def method_missing(symbol, *args, &block)
+      if acts_as_list_method?(symbol)
+        pass_method_to_warning_closer(symbol, args.first)
+      else
+        super
+      end
+    end
+
+  #  Allows acts_as_list methods to be used within the warning. 
+  #  If closers were the act_as_list object, you could do things like this
+  #   
+  #       warning.closers.last.move_higher
+  #       
+  #   However, as closers are used on multiple warnings and they
+  #   need to be independently sortable within each warning, it is the
+  #   through table model WarningCloser that acts_as_list. To change
+  #   position the change must be made in the context of the warning. 
+  #   pass_method_to_warning_closer in combination with method_missing,
+  #   allows you to pass to a warning the acts_as_list method together with
+  #   the closer it needs to effect. The equivalent move_higher call then becomes:
+  #   
+  #       warning.move_higher(warning.closers.last)
+  #       
+  #   You can also do:
+  #   
+  #       warning.move_to_top(closer)
+  #       warning.last?(closer)
+  # 
+    def pass_method_to_warning_closer(symbol, closer)
+      raise "A closer is needed to identify the warning_closer" unless closer.kind_of? Closer
+      warning_closer = warning_closers.where(:closer_id => closer.id).first
+      warning_closer.send(symbol) if warning_closer
+    end
+
+    def acts_as_list_method?(symbol)
+      ActiveRecord::Acts::List::InstanceMethods.instance_methods.include?(symbol.to_sym)
+    end
+    
+  end
+end

data/app/models/ominous/warning_closer.rb

@@ -0,0 +1,11 @@
+require 'acts_as_list'
+module Ominous
+  class WarningCloser < ActiveRecord::Base
+    attr_accessible :warning_id, :closer_id, :position
+    
+    belongs_to :closer
+    belongs_to :warning
+    
+    acts_as_list :scope =>  :warning
+  end
+end

data/app/views/layouts/ominous/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Ominous</title>
+  <%= stylesheet_link_tag    "ominous/application", :media => "all" %>
+  <%= javascript_include_tag "ominous/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

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

@@ -0,0 +1,20 @@
+<% warnings.each do |warning| %>
+<div class="warning">
+  <div class="heading">
+    <h2><%= t("ominous.warning.#{warning.name}.title") %></h2>
+  </div>
+  <div class="description">
+    <%= t("ominous.warning.#{warning.name}.description") %>
+  </div>
+  <div class="closers">
+<%   warning.closers.each do |closer| %> 
+    <div class="<%= classes_for(closer)  %>">
+      <p><%=  t("ominous.warning.#{warning.name}.#{closer.name}.message") %></p>
+      <p>
+        <%= closer_link_to(warning, closer) %>
+      </p>
+    </div>
+<%   end %>
+  </div>
+</div>
+<% end %>

data/config/locales/en.yml

@@ -0,0 +1 @@
+en:

data/config/routes.rb

@@ -0,0 +1,8 @@
+Ominous::Engine.routes.draw do
+  
+  resources :warnings, :only => [:dismiss] do
+    member do
+      put :dismiss
+    end
+  end
+end

data/db/migrate/20121206144249_create_ominous_warnings.rb

@@ -0,0 +1,8 @@
+class CreateOminousWarnings < ActiveRecord::Migration
+  def change
+    create_table :ominous_warnings do |t|
+      t.column :name, :string
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20121206145743_create_ominous_warning_closers.rb

@@ -0,0 +1,10 @@
+class CreateOminousWarningClosers < ActiveRecord::Migration
+  def change
+    create_table :ominous_warning_closers do |t|
+      t.column :warning_id, :integer
+      t.column :closer_id, :integer
+      t.column :position, :integer
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20121206153254_create_ominous_closers.rb

@@ -0,0 +1,11 @@
+class CreateOminousClosers < ActiveRecord::Migration
+  def change
+    create_table :ominous_closers do |t|
+      t.column :name, :string
+      t.column :url, :string
+      t.column :closure_method, :string, :limit => 30
+      t.column :start_hidden, :boolean, :default => false
+      t.timestamps
+    end
+  end
+end

data/lib/ominous/engine.rb

@@ -0,0 +1,14 @@
+module Ominous
+  class Engine < ::Rails::Engine
+    isolate_namespace Ominous
+    
+    initializer 'ominous.action_controller' do |app|
+      ActiveSupport.on_load :action_controller do
+        helper Ominous::ApplicationHelper
+        helper Ominous::WarningsHelper
+      end
+    end
+   
+  end
+end
+

data/lib/ominous/version.rb

@@ -0,0 +1,3 @@
+module Ominous
+  VERSION = "0.0.1"
+end

data/lib/ominous.rb

@@ -0,0 +1,4 @@
+require "ominous/engine"
+
+module Ominous
+end

data/lib/tasks/ominous_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :ominous do
+#   # Task goes here
+# end