activity_notification 0.0.9 → 0.0.10

data/lib/activity_notification/models/concerns/notifier.rb

@@ -9,6 +9,8 @@ module ActivityNotification
     end
 
     class_methods do
+      # Checks if the model includes notifier and notifier methods are available.
+      # @return [Boolean] Always true
       def available_as_notifier?
         true
       end

data/lib/activity_notification/models/concerns/target.rb

@@ -1,55 +1,96 @@
 module ActivityNotification
+  # Target implementation included in target model to notify, like users or administrators.
   module Target
     extend ActiveSupport::Concern
     included do
       include Common
+
+      # Has many notification instances of this target.
+      # @scope instance
+      # @return [Array<Notificaion>] Array or database query of notifications of this target
       has_many :notifications,
         class_name: "::ActivityNotification::Notification",
         as: :target
+
       class_attribute :_notification_email, :_notification_email_allowed, :_notification_devise_resource
       set_target_class_defaults
     end
 
     class_methods do
+      # Checks if the model includes target and target methods are available.
+      # @return [Boolean] Always true
       def available_as_target?
         true
       end
 
+      # Sets default values to target class fields.
+      # @return [Nil] nil
       def set_target_class_defaults
         self._notification_email            = nil
         self._notification_email_allowed    = ActivityNotification.config.email_enabled
         self._notification_devise_resource  = ->(model) { model }
+        nil
       end
     end
 
+    # Returns target email address for email notification.
+    # This method is able to be overriden.
+    #
+    # @return [String] Target email address
     def mailer_to
       resolve_value(_notification_email)
     end
 
+    # Returns if sending notification email is allowed for the target from configured field or overriden method.
+    # This method is able to be overriden.
+    #
+    # @param [Object] notifiable Notifiable instance of the notification
+    # @param [String] key Key of the notification
+    # @return [Boolean] If sending notification email is allowed for the target
     def notification_email_allowed?(notifiable, key)
       resolve_value(_notification_email_allowed, notifiable, key)
     end
 
+    # Returns if current resource signed in with Devise is authenticated for the notification.
+    # This method is able to be overriden.
+    #
+    # @param [Object] current_resource Current resource signed in with Devise
+    # @return [Boolean] If current resource signed in with Devise is authenticated for the notification
     def authenticated_with_devise?(current_resource)
       devise_resource = resolve_value(_notification_devise_resource)
       unless current_resource.instance_of? devise_resource.class
         raise TypeError,
-          "Defferent type of current resource #{current_resource.class.to_s} "\
-          "with devise resource #{devise_resource.class.to_s} has been passed to #{self.class}##{__method__}. "\
+          "Defferent type of current resource #{current_resource.class} "\
+          "with devise resource #{devise_resource.class} has been passed to #{self.class}##{__method__}. "\
           "You have to override #{self.class}##{__method__} method or set devise_resource in acts_as_target."
       end
       current_resource == devise_resource
     end
 
+    # Returns count of unopened notifications of the target.
+    #
+    # @return [Integer] Count of unopened notifications of the target
     def unopened_notification_count
       unopened_notification_index.count
     end
 
+    # Returns if the target has unopened notifications.
+    #
+    # @return [Boolean] If the target has unopened notifications
     def has_unopened_notifications?
       unopened_notification_index.exists?
     end
 
-    #TODO is this switching the best solution?
+    # Gets automatically arranged notification index of the target.
+    # When the target has unopened notifications, returns unopened index with unopened_notification_index.
+    # Otherwise, returns opened index with opened_notification_index.
+    # @todo Is this switching the best solution?
+    #
+    # @example Get automatically arranged notification index of the @user
+    #   @notifications = @user.notification_index
+    #
+    # @param [Integer] limit Limit to query for notifications
+    # @return [Array<Notificaion>] Notification index of the target
     def notification_index(limit = nil)
       # When the target have unopened notifications
       notifications.unopened_index.exists? ?
@@ -61,31 +102,68 @@ module ActivityNotification
           opened_notification_index
     end
 
+    # Gets unopened notification index of the target.
+    #
+    # @example Get unopened notification index of the @user
+    #   @notifications = @user.unopened_notification_index
+    #
+    # @param [Integer] limit Limit to query for notifications
+    # @return [Array<Notificaion>] Unopened notification index of the target
     def unopened_notification_index(limit = nil)
       limit.present? ?
         notifications.unopened_index.limit(limit) :
         notifications.unopened_index
     end
 
+    # Gets opened notification index of the target.
+    #
+    # @example Get opened notification index of the @user
+    #   @notifications = @user.opened_notification_index(10)
+    #
+    # @param [Integer] limit Limit to query for notifications
+    # @return [Array<Notificaion>] Opened notification index of the target
     def opened_notification_index(limit = ActivityNotification.config.opened_limit)
       notifications.opened_index(limit)
     end
 
-
-    # Wrapper methods of Notification class methods
-  
+    # Generates notifications to this target.
+    # This method calls NotificationApi#notify_to internally with self target instance.
+    # @see NotificationApi#notify_to
+    #
+    # @param [Object] notifiable Notifiable instance to notify
+    # @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(notifiable, options = {})
       Notification.notify_to(self, notifiable, options)
     end
   
-    def open_all_notifications(opened_at = nil)
-      Notification.open_all_of(self, opened_at)
+    # Opens all notifications of this target.
+    # This method calls NotificationApi#open_all_of internally with self target instance.
+    # @see NotificationApi#open_all_of
+    #
+    # @param [Hash] options Options for opening notifications
+    # @option options [DateTime] :opened_at (DateTime.now) Time to set to opened_at of the notification record
+    # @return [Integer] Number of opened notification records
+    # @todo Add filter option
+    def open_all_notifications(options = {})
+      Notification.open_all_of(self, options)
     end
 
 
-    # Methods to be overriden
-
-    # Typical method to get notifications index
+    # Gets automatically arranged notification index of the target with included attributes like target, notifiable, group and notifier.
+    # This method is the typical way to get notifications index from controller of view.
+    #
+    # @example Get automatically arranged notification index of the @user with included attributes
+    #   @notifications = @user.notification_index_with_attributes
+    #
+    # @param [Integer] limit Limit to query for notifications
+    # @return [Array<Notificaion>] Notification index of the target with attributes
     def notification_index_with_attributes(limit = nil)
       # When the target have unopened notifications
       unopened_notification_index.exists? ?
@@ -97,25 +175,46 @@ module ActivityNotification
           opened_notification_index_with_attributes
     end
 
+    # Gets unopened notification index of the target with included attributes like target, notifiable, group and notifier.
+    #
+    # @example Get unopened notification index of the @user with included attributes
+    #   @notifications = @user.unopened_notification_index_with_attributes
+    #
+    # @param [Integer] limit Limit to query for notifications
+    # @return [Array<Notificaion>] Unopened notification index of the target with attributes
     def unopened_notification_index_with_attributes(limit = nil)
-      if unopened_notification_index(limit).present?
-        Notification.group_member_exists?(unopened_notification_index(limit)) ?
-          unopened_notification_index(limit).with_target.with_notifiable.with_group.with_notifier :
-          unopened_notification_index(limit).with_target.with_notifiable.with_notifier
-      else
-        notifications.none
-      end
+      include_attributes unopened_notification_index(limit)
     end
 
+    # Gets opened notification index of the target with including attributes like target, notifiable, group and notifier.
+    #
+    # @example Get opened notification index of the @user with included attributes
+    #   @notifications = @user.opened_notification_index_with_attributes(10)
+    #
+    # @param [Integer] limit Limit to query for notifications
+    # @return [Array<Notificaion>] Opened notification index of the target with attributes
     def opened_notification_index_with_attributes(limit = ActivityNotification.config.opened_limit)
-      if opened_notification_index(limit).present?
-        Notification.group_member_exists?(opened_notification_index(limit)) ?
-          opened_notification_index(limit).with_target.with_notifiable.with_group.with_notifier :
-          opened_notification_index(limit).with_target.with_notifiable.with_notifier
-      else
-        notifications.none
-      end
+      include_attributes opened_notification_index(limit)
     end
 
+    private
+
+      # Includes attributes like target, notifiable, group or notifier from the notification index.
+      # When group member exists in the notification index, group will be included in addition to target, notifiable and or notifier.
+      # Otherwise, target, notifiable and or notifier will be include without group.
+      # @api private
+      #
+      # @param [Array<Notificaion>] notification_index Notification index
+      # @return [Array<Notificaion>] Notification index with attributes
+      def include_attributes(notification_index)
+        if notification_index.present?
+          Notification.group_member_exists?(notification_index) ?
+            notification_index.with_target.with_notifiable.with_group.with_notifier :
+            notification_index.with_target.with_notifiable.with_notifier
+        else
+          notifications.none
+        end
+      end
+
   end
 end

data/lib/activity_notification/models/notification.rb

@@ -1,17 +1,43 @@
 module ActivityNotification
+  # Notification model implementation generated by ActivityNotification.
   class Notification < ActiveRecord::Base
     include Renderable
     include Common
     include NotificationApi
     self.table_name = ActivityNotification.config.table_name
   
+    # Belongs to target instance of this notification as polymorphic association.
+    # @scope instance
+    # @return [Object] Target instance of this notification
     belongs_to :target,        polymorphic: true
+
+    # Belongs to notifiable instance of this notification as polymorphic association.
+    # @scope instance
+    # @return [Object] Notifiable instance of this notification
     belongs_to :notifiable,    polymorphic: true
+
+    # Belongs to group instance of this notification as polymorphic association.
+    # @scope instance
+    # @return [Object] Group instance of this notification
     belongs_to :group,         polymorphic: true
+
+    # Belongs to group owner notification instance of this notification.
+    # Only group member instance has :group_owner value.
+    # Group owner instance has nil as :group_owner association.
+    # @scope instance
+    # @return [Notification] Group owner notification instance of this notification
     belongs_to :group_owner,   class_name: :Notification
-    has_many   :group_members,
-      class_name: "::ActivityNotification::Notification",
-      foreign_key: :group_owner_id
+
+    # Has many group member notification instances of this notification.
+    # Only group owner instance has :group_members value.
+    # Group member instance has nil as :group_members association.
+    # @scope instance
+    # @return [Array<Notificaion>] Array or database query of the group member notification instances of this notification
+    has_many   :group_members, class_name: :Notification, foreign_key: :group_owner_id
+
+    # Belongs to :otifier instance of this notification.
+    # @scope instance
+    # @return [Object] Notifier instance of this notification
     belongs_to :notifier,      polymorphic: true
 
     # Serialize parameters Hash
@@ -21,30 +47,168 @@ module ActivityNotification
     validates  :notifiable,    presence: true
     validates  :key,           presence: true
 
+    # Selects group owner notifications only.
+    # @scope class
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :group_owners_only,                 ->        { where(group_owner_id: nil) }
+
+    # Selects group member notifications only.
+    # @scope class
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :group_members_only,                ->        { where.not(group_owner_id: nil) }
+
+    # Selects unopened notifications only.
+    # @scope class
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :unopened_only,                     ->        { where(opened_at: nil) }
+
+    # Selects unopened notification index.
+    # Defined same as `unopened_only.group_owners_only.latest_order`.
+    # @example Get unopened notificaton index of the @user
+    #   @notifications = @user.unopened_index
+    # @scope class
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :unopened_index,                    ->        { unopened_only.group_owners_only.latest_order }
+
+    # Selects opened notifications only without limit.
+    # Be careful to get too many records with this method.
+    # @scope class
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :opened_only!,                      ->        { where.not(opened_at: nil) }
+
+    # Selects opened notifications only with limit.
+    # @scope class
+    # @param [Integer] limit Limit to query for opened notifications
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :opened_only,                       ->(limit) { opened_only!.limit(limit) }
+
+    # Selects unopened notification index.
+    # Defined same as `opened_only(limit).group_owners_only.latest_order`.
+    # @scope class
+    # @param [Integer] limit Limit to query for opened notifications
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :opened_index,                      ->(limit) { opened_only(limit).group_owners_only.latest_order }
+
+    # Selects group member notifications in unopened_index.
+    # @scope class
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :unopened_index_group_members_only, ->        { where(group_owner_id: unopened_index.pluck(:id)) }
-    scope :opened_index_group_members_only,   ->(limit) { where(group_owner_id: opened_index(limit).pluck(:id)) }
 
+    # Selects group member notifications in opened_index.
+    # @scope class
+    # @param [Integer] limit Limit to query for opened notifications
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
+    scope :opened_index_group_members_only,   ->(limit) { where(group_owner_id: opened_index(limit).map(&:id)) }
+
+    # Selects filtered notifications by target instance.
+    #   ActivityNotification::Notification.filtered_by_target(@user)
+    # is the same as
+    #   @user.notifications
+    # @scope class
+    # @param [Object] target Target instance for filter
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :filtered_by_target,   ->(target)             { where(target: target) }
+
+    # Selects filtered notifications by notifiable instance.
+    # @example Get filtered unopened notificatons of the @user for @comment as notifiable
+    #   @notifications = @user.notifications.unopened_only.filtered_by_instance(@comment)
+    # @scope class
+    # @param [Object] notifiable Notifiable instance for filter
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :filtered_by_instance, ->(notifiable)         { where(notifiable: notifiable) }
+
+    # Selects filtered notifications by notifiable_type.
+    # @example Get filtered unopened notificatons of the @user for Comment notifiable class
+    #   @notifications = @user.notifications.unopened_only.filtered_by_type('Comment')
+    # @scope class
+    # @param [String] notifiable_type Notifiable type for filter
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :filtered_by_type,     ->(notifiable_type)    { where(notifiable_type: notifiable_type) }
+
+    # Selects filtered notifications by group instance.
+    # @example Get filtered unopened notificatons of the @user for @article as group
+    #   @notifications = @user.notifications.unopened_only.filtered_by_group(@article)
+    # @scope class
+    # @param [Object] group Group instance for filter
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :filtered_by_group,    ->(group)              { where(group: group) }
+
+    # Selects filtered notifications by key.
+    # @example Get filtered unopened notificatons of the @user with key 'comment.reply'
+    #   @notifications = @user.notifications.unopened_only.filtered_by_key('comment.reply')
+    # @scope class
+    # @param [String] key Key of the notification for filter
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
     scope :filtered_by_key,      ->(key)                { where(key: key) }
 
+    # Selects filtered notifications by notifiable_type, group or key with filter options.
+    # @example Get filtered unopened notificatons of the @user for Comment notifiable class
+    #   @notifications = @user.notifications.unopened_only.filtered_by_options({ filtered_by_type: 'Comment' })
+    # @example Get filtered unopened notificatons of the @user for @article as group
+    #   @notifications = @user.notifications.unopened_only.filtered_by_options({ filtered_by_group: @article })
+    # @example Get filtered unopened notificatons of the @user for Article instance id=1 as group
+    #   @notifications = @user.notifications.unopened_only.filtered_by_options({ filtered_by_group_type: 'Article', filtered_by_group_id: '1' })
+    # @example Get filtered unopened notificatons of the @user with key 'comment.reply'
+    #   @notifications = @user.notifications.unopened_only.filtered_by_options({ filtered_by_key: 'comment.reply' })
+    # @example Get filtered unopened notificatons of the @user for Comment notifiable class with key 'comment.reply'
+    #   @notifications = @user.notifications.unopened_only.filtered_by_options({ filtered_by_type: 'Comment', filtered_by_key: 'comment.reply' })
+    # @scope class
+    # @param [Hash] options Options for filter
+    # @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 [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of filtered notifications
+    scope :filtered_by_options,  ->(options = {})       {
+      options = options.with_indifferent_access
+      filtered_notifications = all
+      if options.has_key?(:filtered_by_type)
+        filtered_notifications = filtered_notifications.filtered_by_type(options[:filtered_by_type])
+      end
+      if options.has_key?(:filtered_by_group)
+        filtered_notifications = filtered_notifications.filtered_by_group(options[:filtered_by_group])
+      end
+      if options.has_key?(:filtered_by_group_type) and options.has_key?(:filtered_by_group_id)
+        filtered_notifications = filtered_notifications
+                                 .where(group_type: options[:filtered_by_group_type], group_id: options[:filtered_by_group_id])
+      end
+      if options.has_key?(:filtered_by_key)
+        filtered_notifications = filtered_notifications.filtered_by_key(options[:filtered_by_key])
+      end
+      filtered_notifications
+    }
+
+    # Includes target instance with query for notifications.
+    # @return [ActiveRecord_AssociationRelation] Database query of notifications with target
     scope :with_target,                       ->        { includes(:target) }
+
+    # Includes notifiable instance with query for notifications.
+    # @return [ActiveRecord_AssociationRelation] Database query of notifications with notifiable
     scope :with_notifiable,                   ->        { includes(:notifiable) }
+
+    # Includes group instance with query for notifications.
+    # @return [ActiveRecord_AssociationRelation] Database query of notifications with group
     scope :with_group,                        ->        { includes(:group) }
+
+    # Includes notifier instance with query for notifications.
+    # @return [ActiveRecord_AssociationRelation] Database query of notifications with notifier
     scope :with_notifier,                     ->        { includes(:notifier) }
 
+    # Orders by latest (newest) first as created_at: :desc.
+    # @return [ActiveRecord_AssociationRelation] Database query of notifications ordered by latest first
     scope :latest_order,                      ->        { order(created_at: :desc) }
+
+    # Orders by earliest (older) first as created_at: :asc.
+    # @return [ActiveRecord_AssociationRelation] Database query of notifications ordered by earliest first
     scope :earliest_order,                    ->        { order(created_at: :asc) }
+
+    # Returns latest notification instance.
+    # @return [Notification] Latest notification instance
     scope :latest,                            ->        { latest_order.first }
+
+    # Returns earliest notification instance.
+    # @return [Notification] Earliest notification instance
     scope :earliest,                          ->        { earliest_order.first }
   end
 end