user_notification 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e1c901c8b0055869556adb983350a2269ca0e3f6
+  data.tar.gz: ad1401b517003379e34d48742132287cee17de93
+SHA512:
+  metadata.gz: 30f2acc2a7562ad950d7336fa5046ccd932c4908668d0c8715d4f6fc851c00d97015db08e352e464beb1ba07eddf56f585c1e6b2c45735036df7b15602230fbf
+  data.tar.gz: f3a169119d6080443fb38ccfc69f161c76561c38ef46b19bc861db2e193d5b8092bb4eacb809bd5a6337c711c73c6d9f142ca85c6210a141ae457c2e408bd9a1

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011-2013 Piotrek Okoński
+
+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.md

@@ -0,0 +1 @@
+# User Notification [![Build Status](https://travis-ci.org/yesmeck/user_notification.png?branch=master)](https://travis-ci.org/yesmeck/user_notification)

data/Rakefile

@@ -0,0 +1,18 @@
+require "bundler/gem_tasks"
+require 'rake'
+require 'yard'
+require 'yard/rake/yardoc_task'
+require 'rake/testtask'
+
+task :default => :test
+
+desc 'Generate documentation for the user_notification plugin.'
+YARD::Rake::YardocTask.new do |doc|
+  doc.files = ['lib/**/*.rb']
+end
+
+Rake::TestTask.new do |t|
+	t.libs << "test"
+	t.test_files = FileList['test/test*.rb']
+end
+

data/lib/generators/user_notification/migration/migration_generator.rb

@@ -0,0 +1,17 @@
+require 'generators/user_notification'
+require 'rails/generators/active_record'
+
+module UserNotification
+  module Generators
+    # Migration generator that creates migration file from template
+    class MigrationGenerator < ActiveRecord::Generators::Base
+      extend Base
+
+      argument :name, :type => :string, :default => 'create_notifications'
+      # Create migration in project's folder
+      def generate_files
+        migration_template 'migration.rb', "db/migrate/#{name}"
+      end
+    end
+  end
+end

data/lib/generators/user_notification/migration/templates/migration.rb

@@ -0,0 +1,24 @@
+# Migration responsible for creating a table with notifications
+class CreateNotifications < ActiveRecord::Migration
+  # Create table
+  def self.up
+    create_table :notifications do |t|
+      t.belongs_to :trackable, :polymorphic => true
+      t.belongs_to :owner, :polymorphic => true
+      t.string  :key
+      t.text    :parameters
+      t.belongs_to :recipient, :polymorphic => true
+      t.boolwan :read, default: false
+
+      t.timestamps
+    end
+
+    add_index :notifications, [:trackable_id, :trackable_type]
+    add_index :notifications, [:owner_id, :owner_type]
+    add_index :notifications, [:recipient_id, :recipient_type]
+  end
+  # Drop table
+  def self.down
+    drop_table :notifications
+  end
+end

data/lib/generators/user_notification/notification/notification_generator.rb

@@ -0,0 +1,17 @@
+require 'generators/user_notification'
+require 'rails/generators/active_record'
+
+module UserNotification
+  module Generators
+    # Notification generator that creates notification model file from template
+    class NotificationGenerator < ActiveRecord::Generators::Base
+      extend Base
+
+      argument :name, :type => :string, :default => 'notification'
+      # Create model in project's folder
+      def generate_files
+        copy_file 'notification.rb', "app/models/#{name}.rb"
+      end
+    end
+  end
+end

data/lib/generators/user_notification/notification/templates/notification.rb

@@ -0,0 +1,3 @@
+# Notification model for customisation & custom methods
+class Notification < UserNotification::Notification
+end

data/lib/generators/user_notification.rb

@@ -0,0 +1,14 @@
+require 'rails/generators/named_base'
+
+module UserNotification
+  # A generator module with Notification table schema.
+  module Generators
+    # A base module
+    module Base
+      # Get path for migration template
+      def source_root
+        @_user_notification_source_root ||= File.expand_path(File.join('../user_notification', generator_name, 'templates'), __FILE__)
+      end
+    end
+  end
+end

data/lib/user_notification/actions/creation.rb

@@ -0,0 +1,15 @@
+module UserNotification
+  # Handles creation of Activities upon destruction and update of tracked model.
+  module Creation
+    extend ActiveSupport::Concern
+
+    included do
+      after_create :notification_on_create
+    end
+    private
+      # Creates notification upon creation of the tracked model
+      def notification_on_create
+        create_notification(:create)
+      end
+  end
+end

data/lib/user_notification/actions/destruction.rb

@@ -0,0 +1,15 @@
+module UserNotification
+  # Handles creation of Activities upon destruction of tracked model.
+  module Destruction
+    extend ActiveSupport::Concern
+
+    included do
+      before_destroy :notification_on_destroy
+    end
+    private
+      # Records an notification upon destruction of the tracked model
+      def notification_on_destroy
+        create_notification(:destroy)
+      end
+  end
+end

data/lib/user_notification/actions/update.rb

@@ -0,0 +1,15 @@
+module UserNotification
+  # Handles creation of Activities upon destruction and update of tracked model.
+  module Update
+    extend ActiveSupport::Concern
+
+    included do
+      after_update :notification_on_update
+    end
+    private
+      # Creates notification upon modification of the tracked model
+      def notification_on_update
+        create_notification(:update)
+      end
+  end
+end

data/lib/user_notification/activity.rb

@@ -0,0 +1,6 @@
+module UserNotification
+  # Main model, stores all information about what happened,
+  # who caused it, when and anything else.
+  class Notification < inherit_orm("Notification")
+  end
+end

data/lib/user_notification/common.rb

@@ -0,0 +1,342 @@
+module UserNotification
+  # Happens when creating custom notifications without either action or a key.
+  class NoKeyProvided < Exception; end
+
+  # Used to smartly transform value from metadata to data.
+  # Accepts Symbols, which it will send against context.
+  # Accepts Procs, which it will execute with controller and context.
+  # @since 0.4.0
+  def self.resolve_value(context, thing)
+    case thing
+    when Symbol
+      context.__send__(thing)
+    when Proc
+      thing.call(UserNotification.get_controller, context)
+    else
+      thing
+    end
+  end
+
+  # Common methods shared across the gem.
+  module Common
+    extend ActiveSupport::Concern
+
+    included do
+      include Trackable
+      class_attribute :notification_owner_global, :notification_recipient_global,
+                      :notification_params_global, :notification_hooks, :notification_custom_fields_global
+      set_user_notification_class_defaults
+    end
+
+    # @!group Global options
+
+    # @!attribute notification_owner_global
+    #   Global version of notification owner
+    #   @see #notification_owner
+    #   @return [Model]
+
+    # @!attribute notification_recipient_global
+    #   Global version of notification recipient
+    #   @see #notification_recipient
+    #   @return [Model]
+
+    # @!attribute notification_params_global
+    #   Global version of notification parameters
+    #   @see #notification_params
+    #   @return [Hash<Symbol, Object>]
+
+    # @!attribute notification_hooks
+    #   @return [Hash<Symbol, Proc>]
+    #   Hooks/functions that will be used to decide *if* the notification should get
+    #   created.
+    #
+    #   The supported keys are:
+    #   * :create
+    #   * :update
+    #   * :destroy
+
+    # @!endgroup
+
+    # @!group Instance options
+
+    # Set or get parameters that will be passed to {Notification} when saving
+    #
+    # == Usage:
+    #
+    #   @article.notification_params = {:article_title => @article.title}
+    #   @article.save
+    #
+    # This way you can pass strings that should remain constant, even when model attributes
+    # change after creating this {Notification}.
+    # @return [Hash<Symbol, Object>]
+    attr_accessor :notification_params
+    @notification_params = {}
+    # Set or get owner object responsible for the {Notification}.
+    #
+    # == Usage:
+    #
+    #   # where current_user is an object of logged in user
+    #   @article.notification_owner = current_user
+    #   # OR: take @article.author association
+    #   @article.notification_owner = :author
+    #   # OR: provide a Proc with custom code
+    #   @article.notification_owner = proc {|controller, model| model.author }
+    #   @article.save
+    #   @article.notifications.last.owner #=> Returns owner object
+    # @return [Model] Polymorphic model
+    # @see #notification_owner_global
+    attr_accessor :notification_owner
+    @notification_owner = nil
+
+    # Set or get recipient for notification.
+    #
+    # Association is polymorphic, thus allowing assignment of
+    # all types of models. This can be used for example in the case of sending
+    # private notifications for only a single user.
+    # @return (see #notification_owner)
+    attr_accessor :notification_recipient
+    @notification_recipient = nil
+    # Set or get custom i18n key passed to {Notification}, later used in {Renderable#text}
+    #
+    # == Usage:
+    #
+    #   @article = Article.new
+    #   @article.notification_key = "my.custom.article.key"
+    #   @article.save
+    #   @article.notifications.last.key #=> "my.custom.article.key"
+    #
+    # @return [String]
+    attr_accessor :notification_key
+    @notification_key = nil
+
+    # Set or get custom fields for later processing
+    #
+    # @return [Hash]
+    attr_accessor :notification_custom_fields
+    @notification_custom_fields = {}
+
+    # @!visibility private
+    @@notification_hooks = {}
+
+    # @!endgroup
+
+    # Provides some global methods for every model class.
+    module ClassMethods
+      #
+      # @since 1.0.0
+      # @api private
+      def set_user_notification_class_defaults
+        self.notification_owner_global             = nil
+        self.notification_recipient_global         = nil
+        self.notification_params_global            = {}
+        self.notification_hooks                    = {}
+        self.notification_custom_fields_global     = {}
+      end
+
+      # Extracts a hook from the _:on_ option provided in
+      # {Tracked::ClassMethods#tracked}. Returns nil when no hook exists for
+      # given action
+      # {Common#get_hook}
+      #
+      # @see Tracked#get_hook
+      # @param key [String, Symbol] action to retrieve a hook for
+      # @return [Proc, nil] callable hook or nil
+      # @since 0.4.0
+      # @api private
+      def get_hook(key)
+        key = key.to_sym
+        if self.notification_hooks.has_key?(key) and self.notification_hooks[key].is_a? Proc
+          self.notification_hooks[key]
+        else
+          nil
+        end
+      end
+    end
+    #
+    # Returns true if UserNotification is enabled
+    # globally and for this class.
+    # @return [Boolean]
+    # @api private
+    # @since 0.5.0
+    def user_notification_enabled?
+      UserNotification.enabled?
+    end
+    #
+    # Shortcut for {ClassMethods#get_hook}
+    # @param (see ClassMethods#get_hook)
+    # @return (see ClassMethods#get_hook)
+    # @since (see ClassMethods#get_hook)
+    # @api (see ClassMethods#get_hook)
+    def get_hook(key)
+      self.class.get_hook(key)
+    end
+
+    # Calls hook safely.
+    # If a hook for given action exists, calls it with model (self) and
+    # controller (if available, see {StoreController})
+    # @param key (see #get_hook)
+    # @return [Boolean] if hook exists, it's decision, if there's no hook, true
+    # @since 0.4.0
+    # @api private
+    def call_hook_safe(key)
+      hook = self.get_hook(key)
+      if hook
+        # provides hook with model and controller
+        hook.call(self, UserNotification.get_controller)
+      else
+        true
+      end
+    end
+
+    # Directly creates notification record in the database, based on supplied options.
+    #
+    # It's meant for creating custom notifications while *preserving* *all*
+    # *configuration* defined before. If you fire up the simplest of options:
+    #
+    #   current_user.create_notification(:avatar_changed)
+    #
+    # It will still gather data from any procs or symbols you passed as params
+    # to {Tracked::ClassMethods#tracked}. It will ask the hooks you defined
+    # whether to really save this notification.
+    #
+    # But you can also overwrite instance and global settings with your options:
+    #
+    #   @article.notification :owner => proc {|controller| controller.current_user }
+    #   @article.create_notification(:commented_on, :owner => @user)
+    #
+    # And it's smart! It won't execute your proc, since you've chosen to
+    # overwrite instance parameter _:owner_ with @user.
+    #
+    # [:key]
+    #   The key will be generated from either:
+    #   * the first parameter you pass that is not a hash (*action*)
+    #   * the _:action_ option in the options hash (*action*)
+    #   * the _:key_ option in the options hash (it has to be a full key,
+    #     including model name)
+    #   When you pass an *action* (first two options above), they will be
+    #   added to parameterized model name:
+    #
+    #   Given Article model and instance: @article,
+    #
+    #     @article.create_notification :commented_on
+    #     @article.notifications.last.key # => "article.commented_on"
+    #
+    # For other parameters, see {Tracked#notification}, and "Instance options"
+    # accessors at {Tracked}, information on hooks is available at
+    # {Tracked::ClassMethods#tracked}.
+    # @see #prepare_settings
+    # @return [Model, nil] If created successfully, new notification
+    # @since 0.4.0
+    # @api public
+    # @overload create_notification(action, options = {})
+    #   @param [Symbol,String] action Name of the action
+    #   @param [Hash] options Options with quality higher than instance options
+    #     set in {Tracked#notification}
+    #   @option options [Activist] :owner Owner
+    #   @option options [Activist] :recipient Recipient
+    #   @option options [Hash] :params Parameters, see
+    #     {UserNotification.resolve_value}
+    # @overload create_notification(options = {})
+    #   @param [Hash] options Options with quality higher than instance options
+    #     set in {Tracked#notification}
+    #   @option options [Symbol,String] :action Name of the action
+    #   @option options [String] :key Full key
+    #   @option options [Activist] :owner Owner
+    #   @option options [Activist] :recipient Recipient
+    #   @option options [Hash] :params Parameters, see
+    #     {UserNotification.resolve_value}
+    def create_notification(*args)
+      return unless self.user_notification_enabled?
+      options = prepare_settings(*args)
+
+      if call_hook_safe(options[:key].split('.').last)
+        reset_notification_instance_options
+        return UserNotification::Adapter.create_notification(self, options)
+      end
+
+      nil
+    end
+
+    # Prepares settings used during creation of Notification record.
+    # params passed directly to tracked model have priority over
+    # settings specified in tracked() method
+    #
+    # @see #create_notification
+    # @return [Hash] Settings with preserved options that were passed
+    # @api private
+    # @overload prepare_settings(action, options = {})
+    #   @see #create_notification
+    # @overload prepare_settings(options = {})
+    #   @see #create_notification
+    def prepare_settings(*args)
+      # key
+      all_options = args.extract_options!
+      options = {
+        key: all_options.delete(:key),
+        action: all_options.delete(:action),
+        parameters: all_options.delete(:parameters) || all_options.delete(:params)
+      }
+      action = (args.first || options[:action]).try(:to_s)
+
+      options[:key] = extract_key(action, options)
+
+      raise NoKeyProvided, "No key provided for #{self.class.name}" unless options[:key]
+
+      options.delete(:action)
+
+      # user responsible for the notification
+      options[:owner] = UserNotification.resolve_value(self,
+        (all_options.has_key?(:owner) ? all_options[:owner] : (
+          self.notification_owner || self.class.notification_owner_global
+          )
+        )
+      )
+
+      # recipient of the notification
+      options[:recipient] = UserNotification.resolve_value(self,
+        (all_options.has_key?(:recipient) ? all_options[:recipient] : (
+          self.notification_recipient || self.class.notification_recipient_global
+          )
+        )
+      )
+
+      #customizable parameters
+      params = {}
+      params.merge!(self.class.notification_params_global)
+      params.merge!(self.notification_params) if self.notification_params
+      params.merge!(options[:params] || options[:parameters] || {})
+      params.each { |k, v| params[k] = UserNotification.resolve_value(self, v) }
+      options[:parameters] = params
+      options.delete(:params)
+
+      customs = self.class.notification_custom_fields_global.clone
+      customs.merge!(self.notification_custom_fields) if self.notification_custom_fields
+      customs.merge!(all_options)
+      customs.each do  |k, v|
+        customs[k] = UserNotification.resolve_value(self, v)
+      end.merge options
+    end
+
+    # Helper method to serialize class name into relevant key
+    # @return [String] the resulted key
+    # @param [Symbol] or [String] the name of the operation to be done on class
+    # @param [Hash] options to be used on key generation, defaults to {}
+    def extract_key(action, options = {})
+      (options[:key] || self.notification_key ||
+        ((self.class.name.underscore.gsub('/', '_') + "." + action.to_s) if action)
+      ).try(:to_s)
+    end
+
+    # Resets all instance options on the object
+    # triggered by a successful #create_notification, should not be
+    # called from any other place, or from application code.
+    # @private
+    def reset_notification_instance_options
+      @notification_params = {}
+      @notification_key = nil
+      @notification_owner = nil
+      @notification_recipient = nil
+      @notification_custom_fields = {}
+    end
+  end
+end

data/lib/user_notification/config.rb

@@ -0,0 +1,63 @@
+require 'singleton'
+
+module UserNotification
+  # Class used to initialize configuration object.
+  class Config
+    include ::Singleton
+    attr_accessor :enabled
+
+    @@orm = :active_record
+
+    def initialize
+      # Indicates whether UserNotification is enabled globally
+      @enabled  = true
+    end
+
+    # Evaluates given block to provide DSL configuration.
+    # @example Initializer for Rails
+    #   UserNotification::Config.set do
+    #     orm :mongo_mapper
+    #     enabled false
+    #   end
+    def self.set &block
+      b = Block.new
+      b.instance_eval &block
+      orm = b.instance_variable_get(:@orm)
+      @@orm = orm unless orm.nil?
+      enabled = b.instance_variable_get(:@en)
+      instance
+      instance.instance_variable_set(:@enabled, enabled) unless enabled.nil?
+    end
+
+    # Set the ORM for use by UserNotification.
+    def self.orm(orm = nil)
+      @@orm = (orm ? orm.to_sym : false) || @@orm
+    end
+
+    # alias for {#orm}
+    # @see #orm
+    def self.orm=(orm = nil)
+      orm(orm)
+    end
+
+    # instance version of {Config#orm}
+    # @see Config#orm
+    def orm(orm=nil)
+      self.class.orm(orm)
+    end
+
+    # Provides simple DSL for the config block.
+    class Block
+      # @see Config#orm
+      def orm(orm = nil)
+        @orm = (orm ? orm.to_sym : false) || @orm
+      end
+
+      # Decides whether to enable UserNotification.
+      # @param en [Boolean] Enabled?
+      def enabled(en = nil)
+        @en = (en.nil? ? @en : en)
+      end
+    end
+  end
+end

data/lib/user_notification/models/activist.rb

@@ -0,0 +1,9 @@
+module UserNotification
+  # Provides helper methods for selecting notifications from a user.
+  module Activist
+    # Delegates to configured ORM.
+    def self.included(base)
+      base.extend UserNotification::inherit_orm("Activist")
+    end
+  end
+end

data/lib/user_notification/models/adapter.rb

@@ -0,0 +1,5 @@
+module UserNotification
+  # Loads database-specific routines for use by UserNotification.
+  class Adapter < inherit_orm("Adapter")
+  end
+end

data/lib/user_notification/models/notification.rb

@@ -0,0 +1,13 @@
+module UserNotification
+  class Notification < inherit_orm("Notification")
+
+    def mark_as_read
+      self.read = true
+    end
+
+    def mark_as_read!
+      self.update_attribute(:read, true)
+    end
+
+  end
+end

data/lib/user_notification/models/trackable.rb

@@ -0,0 +1,9 @@
+module UserNotification
+  # Provides association for notifications bound to this object by *trackable*.
+  module Trackable
+    # Delegates to ORM.
+    def self.included(base)
+      base.extend UserNotification::inherit_orm("Trackable")
+    end
+  end
+end