activity_notification 0.0.9 → 0.0.10

data/lib/activity_notification/mailers/helpers.rb

@@ -1,96 +1,134 @@
 module ActivityNotification
+  # Mailer module of ActivityNotification
   module Mailers
+    # Provides helper methods for mailer.
+    # Use to resolve parameters from email configuration and send notification email.
     module Helpers
       extend ActiveSupport::Concern
 
       protected
 
-      # Configure default email options
-      def notification_mail(notification, options = {})
-        initialize_from_notification(notification)
-        headers = headers_for(notification.key, options)
-        begin
-          mail headers
-        rescue ActionView::MissingTemplate
-          mail headers.merge(template_name: 'default')
+        # Send notification email with configured options.
+        #
+        # @param [Notification] notification Notification instance
+        # @param [Hash] options Options for email notification
+        def notification_mail(notification, options = {})
+          initialize_from_notification(notification)
+          headers = headers_for(notification.key, options)
+          begin
+            mail headers
+          rescue ActionView::MissingTemplate
+            mail headers.merge(template_name: 'default')
+          end
         end
-      end
-
-      def initialize_from_notification(notification)
-        @notification, @target, @notifiable = notification, notification.target, notification.notifiable
-      end
-
-      def headers_for(key, options)
-        if @notifiable.respond_to?(:overriding_notification_email_key) and 
-           @notifiable.overriding_notification_email_key(@target, key).present?
-          key = @notifiable.overriding_notification_email_key(@target, key)
+  
+        # Initialize instance variables from notification.
+        #
+        # @param [Notification] notification Notification instance
+        def initialize_from_notification(notification)
+          @notification, @target, @notifiable = notification, notification.target, notification.notifiable
         end
-        headers = {
-          subject: subject_for(key),
-          to: mailer_to(@target),
-          from: mailer_from(@notification),
-          reply_to: mailer_reply_to(@notification),
-          template_path: template_paths,
-          template_name: template_name(key)
-        }.merge(options)
-
-        @email = headers[:to]
-        headers
-      end
-
-      def mailer_to(target)
-        target.mailer_to
-      end
-
-      def mailer_reply_to(notification)
-        mailer_sender(notification, :reply_to)
-      end
-
-      def mailer_from(notification)
-        mailer_sender(notification, :from)
-      end
-
-      def mailer_sender(notification, sender = :from)
-        default_sender = default_params[sender]
-        if default_sender.present?
-          default_sender.respond_to?(:to_proc) ? instance_eval(&default_sender) : default_sender
-        elsif ActivityNotification.config.mailer_sender.is_a?(Proc)
-          ActivityNotification.config.mailer_sender.call(notification)
-        else
-          ActivityNotification.config.mailer_sender
+  
+        # Prepare email header from notification key and options.
+        #
+        # @param [String] key Key of the notification
+        # @param [Hash] options Options for email notification
+        def headers_for(key, options)
+          if @notifiable.respond_to?(:overriding_notification_email_key) and 
+             @notifiable.overriding_notification_email_key(@target, key).present?
+            key = @notifiable.overriding_notification_email_key(@target, key)
+          end
+          headers = {
+            subject: subject_for(key),
+            to: mailer_to(@target),
+            from: mailer_from(@notification),
+            reply_to: mailer_reply_to(@notification),
+            template_path: template_paths,
+            template_name: template_name(key)
+          }.merge(options)
+  
+          @email = headers[:to]
+          headers
+        end
+  
+        # Returns target email address as 'to'.
+        #
+        # @param [Object] target Target instance to notify
+        # @return [String] Target email address as 'to'
+        def mailer_to(target)
+          target.mailer_to
+        end
+  
+        # Returns sender email address as 'reply_to'.
+        #
+        # @param [Notification] notification Notification instance
+        # @return [String] Sender email address as 'reply_to'
+        def mailer_reply_to(notification)
+          mailer_sender(notification, :reply_to)
+        end
+  
+        # Returns sender email address as 'from'.
+        #
+        # @param [Notification] notification Notification instance
+        # @return [String] Sender email address as 'from'
+        def mailer_from(notification)
+          mailer_sender(notification, :from)
+        end
+  
+        # Returns sender email address configured in initializer or mailer class.
+        #
+        # @param [Notification] notification Notification instance
+        # @return [String] Sender email address configured in initializer or mailer class
+        def mailer_sender(notification, sender = :from)
+          default_sender = default_params[sender]
+          if default_sender.present?
+            default_sender.respond_to?(:to_proc) ? instance_eval(&default_sender) : default_sender
+          elsif ActivityNotification.config.mailer_sender.is_a?(Proc)
+            ActivityNotification.config.mailer_sender.call(notification)
+          else
+            ActivityNotification.config.mailer_sender
+          end
+        end
+  
+        # Returns template paths to find email view
+        #
+        # @return [Array<String>] Template paths to find email view
+        def template_paths
+          paths = ['activity_notification/mailer/default']
+          paths.unshift("activity_notification/mailer/#{@target.to_resources_name}") if @target.present?
+          paths
+        end
+  
+        # Returns template name from notification key
+        #
+        # @param [String] key Key of the notification
+        # @return [String] Template name
+        def template_name(key)
+          key.gsub('.', '/')
+        end
+  
+  
+        # Set up a subject doing an I18n lookup.
+        # At first, it attempts to set a subject based on the current mapping:
+        #   en:
+        #     notification:
+        #       {target}:
+        #         {key}:
+        #           mail_subject: '...'
+        #
+        # If one does not exist, it fallbacks to default:
+        #   Notification for #{notification.printable_type}
+        #
+        # @param [String] key Key of the notification
+        # @return [String] Subject of notification email
+        def subject_for(key)
+          k = key.split('.')
+          k.unshift('notification') if k.first != 'notification'
+          k.insert(1, @target.to_resource_name)
+          k = k.join('.')
+          I18n.t(:mail_subject, scope: k,
+            default: ["Notification of #{@notifiable.printable_type}"])
         end
-      end
-
-      def template_paths
-        paths = ['activity_notification/mailer/default']
-        paths.unshift("activity_notification/mailer/#{@target.to_resources_name}") if @target.present?
-        paths
-      end
-
-      def template_name(key)
-        key.gsub('.', '/')
-      end
-
-
-      # Set up a subject doing an I18n lookup.
-      # At first, it attempts to set a subject based on the current mapping:
-      #   en:
-      #     notification:
-      #       {target}:
-      #         {key}:
-      #           mail_subject: '...'
-      #
-      # If one does not exist, it fallbacks to default:
-      #   Notification for #{notification.printable_type}
-      #
-      def subject_for(key)
-        k = key.split('.')
-        k.unshift('notification') if k.first != 'notification'
-        k.insert(1, @target.to_resource_name)
-        k = k.join('.')
-        I18n.t(:mail_subject, scope: k,
-          default: ["Notification of #{@notifiable.printable_type}"])
-      end
 
     end
   end

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

@@ -1,6 +1,9 @@
 module ActivityNotification
+  # Notifiable implementation included in notifiable model to be notified, like comments or any other user activities.
   module Notifiable
     extend ActiveSupport::Concern
+    # include PolymorphicHelpers to resolve string extentions
+    include ActivityNotification::PolymorphicHelpers
 
     included do
       include Common
@@ -15,15 +18,21 @@ module ActivityNotification
       set_notifiable_class_defaults
     end
   
+    # Returns default_url_options for polymorphic_path.
+    # @return [Hash] Rails.application.routes.default_url_options
     def default_url_options
       Rails.application.routes.default_url_options
     end
     
     class_methods do
+      # Checks if the model includes notifiable and notifiable methods are available.
+      # @return [Boolean] Always true
       def available_as_notifiable?
         true
       end
 
+      # Sets default values to notifiable class fields.
+      # @return [Nil] nil
       def set_notifiable_class_defaults
         self._notification_targets        = {}
         self._notification_group          = {}
@@ -31,111 +40,195 @@ module ActivityNotification
         self._notification_parameters     = {}
         self._notification_email_allowed  = {}
         self._notifiable_path             = {}
+        nil
       end
     end
 
-    # Methods to be overriden
-
+    # Returns notification targets from configured field or overriden method.
+    # This method is able to be overriden.
+    #
+    # @param [String] target_type Target type to notify
+    # @param [String] key Key of the notification
+    # @return [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] Array or database query of the notification targets
     def notification_targets(target_type, key)
-      plural_target_type       = target_type.to_s.underscore.pluralize
-      plural_target_type_sym   = plural_target_type.to_sym
-      target_typed_method_name = "notification_#{plural_target_type}"
-      if respond_to?(target_typed_method_name)
-        send(target_typed_method_name, key)
-      else
-        if _notification_targets[plural_target_type_sym]
-          resolve_value(_notification_targets[plural_target_type_sym], key)
-        else
-          raise NotImplementedError, "You have to implement #{self.class}##{target_typed_method_name} or set :targets in acts_as_notifiable"
-        end
+      target_typed_method_name = "notification_#{target_type.to_s.to_resources_name}"
+      resolved_parameter = resolve_parameter(
+        target_typed_method_name,
+        _notification_targets[target_type.to_s.to_resources_name.to_sym],
+        nil,
+        key)
+      unless resolved_parameter
+        raise NotImplementedError, "You have to implement #{self.class}##{target_typed_method_name} "\
+                                   "or set :targets in acts_as_notifiable"
       end
+      resolved_parameter
     end
 
+    # Returns group owner of the notification from configured field or overriden method.
+    # This method is able to be overriden.
+    #
+    # @param [String] target_type Target type to notify
+    # @param [String] key Key of the notification
+    # @return [Object] Group owner of the notification
     def notification_group(target_type, key)
-      plural_target_type       = target_type.to_s.underscore.pluralize
-      plural_target_type_sym   = plural_target_type.to_sym
-      target_typed_method_name = "notification_group_for_#{plural_target_type}"
-      if respond_to?(target_typed_method_name)
-        send(target_typed_method_name, key)
-      else
-        resolve_value(_notification_group[plural_target_type_sym], key)
-      end
+      resolve_parameter(
+        "notification_group_for_#{target_type.to_s.to_resources_name}",
+        _notification_group[target_type.to_s.to_resources_name.to_sym],
+        nil,
+        key)
     end
 
+    # Returns additional notification parameters from configured field or overriden method.
+    # This method is able to be overriden.
+    #
+    # @param [String] target_type Target type to notify
+    # @param [String] key Key of the notification
+    # @return [Hash] Additional notification parameters
     def notification_parameters(target_type, key)
-      plural_target_type       = target_type.to_s.underscore.pluralize
-      plural_target_type_sym   = plural_target_type.to_sym
-      target_typed_method_name = "notification_parameters_for_#{plural_target_type}"
-      if respond_to?(target_typed_method_name)
-        send(target_typed_method_name, key)
-      else
-        resolve_value(_notification_parameters[plural_target_type_sym], key) || {}
-      end
+      resolve_parameter(
+        "notification_parameters_for_#{target_type.to_s.to_resources_name}",
+        _notification_parameters[target_type.to_s.to_resources_name.to_sym],
+        {},
+        key)
     end
 
+    # Returns notifier of the notification from configured field or overriden method.
+    # This method is able to be overriden.
+    #
+    # @param [String] target_type Target type to notify
+    # @param [String] key Key of the notification
+    # @return [Object] Notifier of the notification
     def notifier(target_type, key)
-      plural_target_type       = target_type.to_s.underscore.pluralize
-      plural_target_type_sym   = plural_target_type.to_sym
-      target_typed_method_name = "notifier_for_#{plural_target_type}"
-      if respond_to?(target_typed_method_name)
-        send(target_typed_method_name, key)
-      else
-        resolve_value(_notifier[plural_target_type_sym], key)
-      end
+      resolve_parameter(
+        "notifier_for_#{target_type.to_s.to_resources_name}",
+        _notifier[target_type.to_s.to_resources_name.to_sym],
+        nil,
+        key)
     end
 
+    # Returns if sending notification email is allowed for the notifiable from configured field or overriden method.
+    # This method is able to be overriden.
+    #
+    # @param [Object] target Target instance to notify
+    # @param [String] key Key of the notification
+    # @return [Boolean] If sending notification email is allowed for the notifiable
     def notification_email_allowed?(target, key)
-      plural_target_type       = target.class.to_s.underscore.pluralize
-      plural_target_type_sym   = target.to_resources_name.to_sym
-      target_typed_method_name = "notification_email_allowed_for_#{plural_target_type}?"
-      if respond_to?(target_typed_method_name)
-        send(target_typed_method_name, target, key)
-      elsif _notification_email_allowed[plural_target_type_sym]
-        resolve_value(_notification_email_allowed[plural_target_type_sym], target, key)
-      else
-        ActivityNotification.config.email_enabled
-      end
+      resolve_parameter(
+        "notification_email_allowed_for_#{target.class.to_s.to_resources_name}?",
+        _notification_email_allowed[target.class.to_s.to_resources_name.to_sym],
+        ActivityNotification.config.email_enabled,
+        target, key)
     end
 
-    def notifiable_path(target_type, key = nil)
-      plural_target_type       = target_type.to_s.underscore.pluralize
-      plural_target_type_sym   = plural_target_type.to_sym
-      target_typed_method_name = "notifiable_path_for_#{plural_target_type}"
-      if respond_to?(target_typed_method_name)
-        send(target_typed_method_name, key)
-      elsif _notifiable_path[plural_target_type_sym]
-        resolve_value(_notifiable_path[plural_target_type_sym], key)
-      else
+    # Returns notifiable_path to move after opening notification from configured field or overriden method.
+    # This method is able to be overriden.
+    #
+    # @param [String] target_type Target type to notify
+    # @param [String] key Key of the notification
+    # @return [String] Notifiable path URL to move after opening notification
+    def notifiable_path(target_type, key)
+      resolved_parameter = resolve_parameter(
+        "notifiable_path_for_#{target_type.to_s.to_resources_name}",
+        _notifiable_path[target_type.to_s.to_resources_name.to_sym],
+        nil,
+        key)
+      unless resolved_parameter
         begin
-          polymorphic_path(self)
+          resolved_parameter = polymorphic_path(self)
         rescue NoMethodError, ActionController::UrlGenerationError
-          raise NotImplementedError, "You have to implement #{self.class}##{__method__}, set :notifiable_path in acts_as_notifiable or set polymorphic_path routing for #{self.class}"
+          raise NotImplementedError, "You have to implement #{self.class}##{__method__}, "\
+                                     "set :notifiable_path in acts_as_notifiable or "\
+                                     "set polymorphic_path routing for #{self.class}"
         end
       end
+      resolved_parameter
     end
 
-    # TODO docs
-    # overriding_notification_render_key(target, key)
-
-    # TODO docs
+    # overriding_notification_email_key is the method to override key definition for Mailer
+    # When respond_to?(overriding_notification_email_key) returns true,
+    # Mailer uses overriding_notification_email_key instead of original key.
+    #
     # overriding_notification_email_key(target, key)
 
-    # Wrapper methods of Notification class methods
-  
+
+    # Generates notifications to configured targets with notifiable model.
+    # This method calls NotificationApi#notify internally with self notifiable instance.
+    # @see NotificationApi#notify
+    #
+    # @param [Symbol, String, Class] target_type Type of target
+    # @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, options = {})
       Notification.notify(target_type, self, options)
     end
-  
-    def notify_to(target, options = {})
-      Notification.notify_to(target, self, options)
-    end
-  
+
+    # Generates notifications to one target.
+    # This method calls NotificationApi#notify_all internally with self notifiable instance.
+    # @see NotificationApi#notify_all
+    #
+    # @param [Array<Object>] targets Targets to send notifications
+    # @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, options = {})
       Notification.notify_all(targets, self, options)
     end
 
+    # Generates notifications to one target.
+    # This method calls NotificationApi#notify_to internally with self notifiable instance.
+    # @see NotificationApi#notify_to
+    #
+    # @param [Object] target Target to send notifications
+    # @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, options = {})
+      Notification.notify_to(target, self, options)
+    end
+
+    # Returns default key of the notification.
+    # This method is able to be overriden.
+    # "#{to_resource_name}.default" is defined as default key.
+    #
+    # @return [String] Default Key of the notification
     def default_notification_key
       "#{to_resource_name}.default"
     end
+
+    private
+
+      # Used to transform parameter value from configured field or defined method.
+      # @api private
+      #
+      # @param [String] target_typed_method_name Method name overriden for the target type
+      # @param [Object] parameter_field Parameter Configured field in this model
+      # @param [Object] default_value Default parameter value
+      # @param [Array] args Arguments to pass to the method overriden or defined as parameter field
+      # @return [Object] Resolved parameter value
+      def resolve_parameter(target_typed_method_name, parameter_field, default_value, *args)
+        if respond_to?(target_typed_method_name)
+          send(target_typed_method_name, *args)
+        elsif parameter_field
+          resolve_value(parameter_field, *args)
+        else
+          default_value
+        end
+      end
   end
 end