activity_notification 0.0.9 → 0.0.10

data/gemfiles/Gemfile.rails-5.0

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+gemspec path: '../'
+
+gem 'rails', '~> 5.0.0'
+gem 'sqlite3'
+gem 'jquery-rails'
+
+group :test do
+  gem 'ammeter'
+  gem 'rails-controller-testing'
+  gem 'timecop'
+  gem 'coveralls', require: false
+end

data/gemfiles/Gemfile.rails-5.0.lock

@@ -0,0 +1,201 @@
+PATH
+  remote: ../
+  specs:
+    activity_notification (0.0.9)
+      activerecord (>= 4.2.0)
+      i18n (>= 0.5.0)
+      railties (>= 4.2.0, < 5.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (5.0.0.1)
+      actionpack (= 5.0.0.1)
+      nio4r (~> 1.2)
+      websocket-driver (~> 0.6.1)
+    actionmailer (5.0.0.1)
+      actionpack (= 5.0.0.1)
+      actionview (= 5.0.0.1)
+      activejob (= 5.0.0.1)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (5.0.0.1)
+      actionview (= 5.0.0.1)
+      activesupport (= 5.0.0.1)
+      rack (~> 2.0)
+      rack-test (~> 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.0.0.1)
+      activesupport (= 5.0.0.1)
+      builder (~> 3.1)
+      erubis (~> 2.7.0)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    activejob (5.0.0.1)
+      activesupport (= 5.0.0.1)
+      globalid (>= 0.3.6)
+    activemodel (5.0.0.1)
+      activesupport (= 5.0.0.1)
+    activerecord (5.0.0.1)
+      activemodel (= 5.0.0.1)
+      activesupport (= 5.0.0.1)
+      arel (~> 7.0)
+    activesupport (5.0.0.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (~> 0.7)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    ammeter (1.1.3)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-rails (>= 2.2)
+    arel (7.1.1)
+    bcrypt (3.1.11)
+    builder (3.2.2)
+    concurrent-ruby (1.0.2)
+    coveralls (0.8.15)
+      json (>= 1.8, < 3)
+      simplecov (~> 0.12.0)
+      term-ansicolor (~> 1.3)
+      thor (~> 0.19.1)
+      tins (>= 1.6.0, < 2)
+    devise (4.2.0)
+      bcrypt (~> 3.0)
+      orm_adapter (~> 0.1)
+      railties (>= 4.1.0, < 5.1)
+      responders
+      warden (~> 1.2.3)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    erubis (2.7.0)
+    factory_girl (4.7.0)
+      activesupport (>= 3.0.0)
+    factory_girl_rails (4.7.0)
+      factory_girl (~> 4.7.0)
+      railties (>= 3.0.0)
+    globalid (0.3.7)
+      activesupport (>= 4.1.0)
+    i18n (0.7.0)
+    jquery-rails (4.2.1)
+      rails-dom-testing (>= 1, < 3)
+      railties (>= 4.2.0)
+      thor (>= 0.14, < 2.0)
+    json (2.0.2)
+    loofah (2.0.3)
+      nokogiri (>= 1.5.9)
+    mail (2.6.4)
+      mime-types (>= 1.16, < 4)
+    method_source (0.8.2)
+    mime-types (3.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2016.0521)
+    mini_portile2 (2.1.0)
+    minitest (5.9.0)
+    nio4r (1.2.1)
+    nokogiri (1.6.8)
+      mini_portile2 (~> 2.1.0)
+      pkg-config (~> 1.1.7)
+    orm_adapter (0.5.0)
+    pkg-config (1.1.7)
+    rack (2.0.1)
+    rack-test (0.6.3)
+      rack (>= 1.0)
+    rails (5.0.0.1)
+      actioncable (= 5.0.0.1)
+      actionmailer (= 5.0.0.1)
+      actionpack (= 5.0.0.1)
+      actionview (= 5.0.0.1)
+      activejob (= 5.0.0.1)
+      activemodel (= 5.0.0.1)
+      activerecord (= 5.0.0.1)
+      activesupport (= 5.0.0.1)
+      bundler (>= 1.3.0, < 2.0)
+      railties (= 5.0.0.1)
+      sprockets-rails (>= 2.0.0)
+    rails-controller-testing (1.0.1)
+      actionpack (~> 5.x)
+      actionview (~> 5.x)
+      activesupport (~> 5.x)
+    rails-dom-testing (2.0.1)
+      activesupport (>= 4.2.0, < 6.0)
+      nokogiri (~> 1.6.0)
+    rails-html-sanitizer (1.0.3)
+      loofah (~> 2.0)
+    railties (5.0.0.1)
+      actionpack (= 5.0.0.1)
+      activesupport (= 5.0.0.1)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (11.2.2)
+    responders (2.3.0)
+      railties (>= 4.2.0, < 5.1)
+    rspec-core (3.5.2)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-rails (3.5.2)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+    simplecov (0.12.0)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    sprockets (3.7.0)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.1.1)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    sqlite3 (1.3.11)
+    term-ansicolor (1.3.2)
+      tins (~> 1.0)
+    thor (0.19.1)
+    thread_safe (0.3.5)
+    timecop (0.8.1)
+    tins (1.12.0)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+    warden (1.2.6)
+      rack (>= 1.0)
+    websocket-driver (0.6.4)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.2)
+    yard (0.9.5)
+    yard-activesupport-concern (0.0.1)
+      yard (>= 0.8)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activity_notification!
+  ammeter
+  coveralls
+  devise (~> 4.2.0)
+  factory_girl_rails (~> 4.7.0)
+  jquery-rails
+  rails (~> 5.0.0)
+  rails-controller-testing
+  rspec-rails (~> 3.5.1)
+  simplecov (~> 0.12.0)
+  sqlite3
+  timecop
+  yard (~> 0.9.5)
+  yard-activesupport-concern (~> 0.0.1)
+
+BUNDLED WITH
+   1.12.5

data/lib/activity_notification.rb

@@ -22,19 +22,23 @@ module ActivityNotification
     autoload :Helpers,        'activity_notification/mailers/helpers'
   end
 
-  # Returns ActivityNotification's configuration object.
+  # Returns configuration object of ActivityNotification.
   def self.config
     @config ||= ActivityNotification::Config.new
   end
 
-  # Lets you set global configuration options.
-  #
+  # Sets global configuration options for ActivityNotification.
   # All available options and their defaults are in the example below:
   # @example Initializer for Rails
   #   ActivityNotification.configure do |config|
-  #     config.enabled       = false
-  #     config.table_name    = "notifications"
-  #     ...
+  #     config.enabled           = true
+  #     config.table_name        = "notifications"
+  #     config.email_enabled     = false
+  #     config.mailer_sender     = nil
+  #     config.mailer            = 'ActivityNotification::Mailer'
+  #     config.parent_mailer     = 'ActionMailer::Base'
+  #     config.parent_controller = 'ApplicationController'
+  #     config.opened_limit      = 10
   #   end
   def self.configure(&block)
     yield(config) if block_given?

data/lib/activity_notification/apis/notification_api.rb

@@ -1,25 +1,77 @@
 module ActivityNotification
+  # Defines API for notification included in Notification model.
   module NotificationApi
     extend ActiveSupport::Concern
 
-    # Define store_notification as private clas method
     included do
+      # Defines store_notification as private clas method
       private_class_method :store_notification
     end
 
-    # For notification API
     class_methods do
+      # Generates notifications to configured targets with notifiable model.
+      #
+      # @example Use with target_type as Symbol
+      #   ActivityNotification::Notification.notify :users, @comment
+      # @example Use with target_type as String
+      #   ActivityNotification::Notification.notify 'User', @comment
+      # @example Use with target_type as Class
+      #   ActivityNotification::Notification.notify User, @comment
+      # @example Use with options
+      #   ActivityNotification::Notification.notify :users, @comment, key: 'custom.comment', group: @comment.article
+      #   ActivityNotification::Notification.notify :users, @comment, parameters: { reply_to: @comment.reply_to }, send_later: false
+      #
+      # @param [Symbol, String, Class] target_type Type of target
+      # @param [Object] notifiable Notifiable instance
+      # @param [Hash] options Options for notifications
+      # @option options [String]  :key        (notifiable.default_notification_key) Key of the notification
+      # @option options [Object]  :group      (nil)                                 Group unit of the notifications
+      # @option options [Object]  :notifier   (nil)                                 Notifier of the notifications
+      # @option options [Hash]    :parameters ({})                                  Additional parameters of the notifications
+      # @option options [Boolean] :send_email (true)                                If it sends notification email
+      # @option options [Boolean] :send_later (true)                                If it sends notification email asynchronously
+      # @return [Array<Notificaion>] Array of generated notifications
       def notify(target_type, notifiable, options = {})
         targets = notifiable.notification_targets(target_type, options[:key])
         unless targets.blank?
           notify_all(targets, notifiable, options)
         end
       end
-    
+
+      # Generates notifications to specified targets.
+      #
+      # @example Notify to all users
+      #   ActivityNotification::Notification.notify_all User.all, @comment
+      #
+      # @param [Array<Object>] targets Targets to send notifications
+      # @param [Object] notifiable Notifiable instance
+      # @param [Hash] options Options for notifications
+      # @option options [String]  :key        (notifiable.default_notification_key) Key of the notification
+      # @option options [Object]  :group      (nil)                                 Group unit of the notifications
+      # @option options [Object]  :notifier   (nil)                                 Notifier of the notifications
+      # @option options [Hash]    :parameters ({})                                  Additional parameters of the notifications
+      # @option options [Boolean] :send_email (true)                                Whether it sends notification email
+      # @option options [Boolean] :send_later (true)                                Whether it sends notification email asynchronously
+      # @return [Array<Notificaion>] Array of generated notifications
       def notify_all(targets, notifiable, options = {})
         Array(targets).map { |target| notify_to(target, notifiable, options) }
       end
-    
+
+      # Generates notifications to one target.
+      #
+      # @example Notify to one user
+      #   ActivityNotification::Notification.notify_to @comment.auther, @comment
+      #
+      # @param [Object] target Target to send notifications
+      # @param [Object] notifiable Notifiable instance
+      # @param [Hash] options Options for notifications
+      # @option options [String]  :key        (notifiable.default_notification_key) Key of the notification
+      # @option options [Object]  :group      (nil)                                 Group unit of the notifications
+      # @option options [Object]  :notifier   (nil)                                 Notifier of the notifications
+      # @option options [Hash]    :parameters ({})                                  Additional parameters of the notifications
+      # @option options [Boolean] :send_email (true)                                Whether it sends notification email
+      # @option options [Boolean] :send_later (true)                                Whether it sends notification email asynchronously
+      # @return [Notification] Generated notification instance
       def notify_to(target, notifiable, options = {})
         send_email = options.has_key?(:send_email) ? options[:send_email] : true
         send_later = options.has_key?(:send_later) ? options[:send_later] : true
@@ -30,25 +82,42 @@ module ActivityNotification
         # Return created notification
         notification
       end
-  
-      # Open all notifications of specified target
-      def open_all_of(target, opened_at = nil)
-        opened_at = DateTime.now if opened_at.blank?
-        where(target: target, opened_at: nil).update_all(opened_at: opened_at)
+
+      # Opens all notifications of the target.
+      #
+      # @param [Object] target Target of the notifications to open
+      # @param [Hash] options Options for opening notifications
+      # @option options [DateTime] :opened_at (DateTime.now) Time to set to opened_at of the notification record
+      # @option options [String]   :filtered_by_type       (nil) Notifiable type for filter
+      # @option options [Object]   :filtered_by_group      (nil) Group instance for filter
+      # @option options [String]   :filtered_by_group_type (nil) Group type for filter, valid with :filtered_by_group_id
+      # @option options [String]   :filtered_by_group_id   (nil) Group instance id for filter, valid with :filtered_by_group_type
+      # @option options [String]   :filtered_by_key        (nil) Key of the notification for filter 
+      # @return [Integer] Number of opened notification records
+      # @todo Add filter option
+      def open_all_of(target, options = {})
+        opened_at = options[:opened_at] || DateTime.now
+        target.notifications.unopened_only.filtered_by_options(options).update_all(opened_at: opened_at)
       end
   
-      #TODO description
-      # Call from controllers or views to avoid N+1
+      # Returns if group member of the notifications exists.
+      # This method is designed to be called from controllers or views to avoid N+1.
+      #
+      # @param [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] notifications Array or database query of the notifications to test member exists
+      # @return [Boolean] If group member of the notifications exists
       def group_member_exists?(notifications)
-        notifications.present? && where(group_owner_id: notifications.pluck(:id)).exists?
+        notifications.present? && where(group_owner_id: notifications.map(&:id)).exists?
       end
-    
+
+      # Returns available options for kinds of notify methods.
+      #
+      # @return [Array<Notificaion>] Available options for kinds of notify methods
       def available_options
         [:key, :group, :parameters, :notifier, :send_email, :send_later].freeze
       end
 
-      # Private class methods
-  
+      # Stores notifications to datastore
+      # @api private
       def store_notification(target, notifiable, options = {})
         target_type = target.to_class_name
         key         = options[:key]        || notifiable.default_notification_key
@@ -57,7 +126,7 @@ module ActivityNotification
         parameters  = options[:parameters] || {}
         parameters.merge!(options.except(*available_options))
         parameters.merge!(notifiable.notification_parameters(target_type, key))
-  
+
         # Bundle notification group by target, notifiable_type, group and key
         # Defferent notifiable.id can be made in a same group
         group_owner = where(target: target, notifiable_type: notifiable.to_class_name, key: key, group: group)
@@ -71,8 +140,10 @@ module ActivityNotification
     end
 
 
-    # Public instance methods
-
+    # Sends notification email to the target.
+    #
+    # @param [Boolean] send_later If it sends notification email asynchronously
+    # @return [Mail::Message, ActionMailer::DeliveryJob] Email message or its delivery job
     def send_notification_email(send_later = true)
       if send_later
         Mailer.send_notification_email(self).deliver_later
@@ -81,34 +152,61 @@ module ActivityNotification
       end
     end
 
-    def open!(opened_at = nil)
-      opened_at = DateTime.now if opened_at.blank?
+    # Opens the notification.
+    #
+    # @param [Hash] options Options for opening notifications
+    # @option options [DateTime] :opened_at (DateTime.now) Time to set to opened_at of the notification record
+    # @option options [Boolean] :with_members (true) If it opens notifications including group members
+    # @return [Integer] Number of opened notification records
+    def open!(options = {})
+      opened_at = options[:opened_at] || DateTime.now
+      with_members = options.has_key?(:with_members) ? options[:with_members] : true
       update(opened_at: opened_at)
-      group_members.update_all(opened_at: opened_at) + 1
+      with_members ? group_members.update_all(opened_at: opened_at) + 1 : 1
     end
 
+    # Returns if the notification is unopened.
+    #
+    # @return [Boolean] If the notification is unopened
     def unopened?
       !opened?
     end
 
+    # Returns if the notification is opened.
+    #
+    # @return [Boolean] If the notification is opened
     def opened?
       opened_at.present?
     end
 
+    # Returns if the notification is group owner.
+    #
+    # @return [Boolean] If the notification is group owner
     def group_owner?
       group_owner_id.blank?
     end
 
+    # Returns if the notification is group member belonging to owner.
+    #
+    # @return [Boolean] If the notification is group member
     def group_member?
       group_owner_id.present?
     end
   
-    # Cache group-by query result to avoid N+1 call
+    # Returns if group member of the notification exists.
+    # This method is designed to cache group by query result to avoid N+1 call.
+    #
+    # @param [Integer] limit Limit to query for opened notifications
+    # @return [Boolean] If group member of the notification exists
     def group_member_exists?(limit = ActivityNotification.config.opened_limit)
       group_member_count(limit) > 0
     end
 
-    # Cache group-by query result to avoid N+1 call
+    # Returns count of group members of the notification.
+    # This method is designed to cache group by query result to avoid N+1 call.
+    #
+    # @param [Integer] limit Limit to query for opened notifications
+    # @return [Integer] Count of group members of the notification
     def group_member_count(limit = ActivityNotification.config.opened_limit)
       notification = group_member? ? group_owner : self
       notification.opened? ?
@@ -116,16 +214,23 @@ module ActivityNotification
         notification.unopened_group_member_count
     end
 
+    # Returns notifiable_path to move after opening notification with notifiable.notifiable_path.
+    #
+    # @return [String] Notifiable path URL to move after opening notification
     def notifiable_path
-      notifiable.notifiable_path(target_type)
+      notifiable.notifiable_path(target_type, key)
     end
 
 
-    # Protected instance methods
     protected
 
+      # Returns count of group members of the unopened notification.
+      # This method is designed to cache group by query result to avoid N+1 call.
+      # @api protected
+      #
+      # @return [Integer] Count of group members of the unopened notification
       def unopened_group_member_count
-        # Cache group-by query result to avoid N+1 call
+        # Cache group by query result to avoid N+1 call
         unopened_group_member_counts = target.notifications
                                              .unopened_index_group_members_only
                                              .group(:group_owner_id)
@@ -133,8 +238,13 @@ module ActivityNotification
         unopened_group_member_counts[id] || 0
       end
     
+      # Returns count of group members of the opened notification.
+      # This method is designed to cache group by query result to avoid N+1 call.
+      # @api protected
+      #
+      # @return [Integer] Count of group members of the opened notification
       def opened_group_member_count(limit = ActivityNotification.config.opened_limit)
-        # Cache group-by query result to avoid N+1 call
+        # Cache group by query result to avoid N+1 call
         opened_group_member_counts   = target.notifications
                                              .opened_index_group_members_only(limit)
                                              .group(:group_owner_id)