activity_notification 0.0.9 → 0.0.10

data/lib/activity_notification/common.rb

@@ -4,27 +4,31 @@ module ActivityNotification
   # Accepts Symbols, which it will send against context.
   # Accepts Procs, which it will execute with controller and context.
   # Both Symbols and Procs will be passed arguments of this method.
+  # Also accepts Hash of these Symbols or Procs.
+  # If any other value will be passed, returns original value.
+  #
+  # @param [Object] context Context to resolve parameter, which is usually target or notificable model
+  # @param [Symbol, Proc, Hash, Object] thing Symbol or Proc to resolve parameter
+  # @param [Array] args Arguments to pass to thing as method
+  # @return [Object] Resolved parameter value
   def self.resolve_value(context, thing, *args)
     case thing
     when Symbol
-      begin
-        context.__send__(thing, ActivityNotification.get_controller, *args)
-      rescue ArgumentError
-        begin
-          context.__send__(thing, ActivityNotification.get_controller)
-        rescue ArgumentError
-          context.__send__(thing)
-        end
+      symbol_method = context.method(thing)
+      if symbol_method.arity > 1
+        symbol_method.call(ActivityNotification.get_controller, *args)
+      elsif symbol_method.arity > 0
+        symbol_method.call(ActivityNotification.get_controller)
+      else
+        symbol_method.call
       end
     when Proc
-      begin
+      if thing.arity > 2
         thing.call(ActivityNotification.get_controller, context, *args)
-      rescue ArgumentError
-        begin
-          thing.call(ActivityNotification.get_controller, context)
-        rescue ArgumentError
-          thing.call(context)
-        end
+      elsif thing.arity > 1
+        thing.call(ActivityNotification.get_controller, context)
+      else
+        thing.call(context)
       end
     when Hash
       thing.dup.tap do |hash|
@@ -37,24 +41,34 @@ module ActivityNotification
     end
   end
 
+  # Common module included in target and notifiable model.
+  # Provides methods to resolve parameters from configured field or defined method.
+  # Also provides methods to convert into resource name or class name as string.
   module Common
 
     # Used to transform value from metadata to data which belongs model instance.
-    # Accepts Symbols, which it will send against this instance.
+    # Accepts Symbols, which it will send against this instance,
     # Accepts Procs, which it will execute with this instance.
     # Both Symbols and Procs will be passed arguments of this method.
+    # Also accepts Hash of these Symbols or Procs.
+    # If any other value will be passed, returns original value.
+    #
+    # @param [Symbol, Proc, Hash, Object] thing Symbol or Proc to resolve parameter
+    # @param [Array] args Arguments to pass to thing as method
+    # @return [Object] Resolved parameter value
     def resolve_value(thing, *args)
       case thing
       when Symbol
-        begin
-          __send__(thing, *args)
-        rescue ArgumentError
-          __send__(thing)
+        symbol_method = method(thing)
+        if symbol_method.arity > 0
+          symbol_method.call(*args)
+        else
+          symbol_method.call
         end
       when Proc
-        begin
+        if thing.arity > 1
           thing.call(self, *args)
-        rescue ArgumentError
+        else
           thing.call(self)
         end
       when Hash
@@ -68,24 +82,34 @@ module ActivityNotification
       end
     end
 
+    # Convets to class name.
+    # @return [String] Class name
     def to_class_name
       self.class.name
     end
 
+    # Convets to singularized model name (resource name).
+    # @return [String] Singularized model name (resource name)
     def to_resource_name
       self.class.name.demodulize.singularize.underscore
     end
 
+    # Convets to pluralized model name (resources name).
+    # @return [String] Pluralized model name (resources name)
     def to_resources_name
       self.class.name.demodulize.pluralize.underscore
     end
 
-    #TODO Is it the best solution?
+    # Convets to printable model type name to be humanized.
+    # @return [String] Printable model type name
+    # @todo Is this the best to make readable?
     def printable_type
       "#{self.class.name.demodulize.humanize}"
     end
 
-    #TODO Is it the best solution?
+    # Convets to printable model name to show in view or email.
+    # @return [String] Printable model name
+    # @todo Is this the best to make readable?
     def printable_name
       "#{self.printable_type} (#{id})"
     end

data/lib/activity_notification/config.rb

@@ -1,21 +1,79 @@
 module ActivityNotification
   # Class used to initialize configuration object.
   class Config
-    attr_accessor :enabled,
-                  :table_name,
-                  :email_enabled,
-                  :mailer_sender,
-                  :mailer,
-                  :parent_mailer,
-                  :parent_controller,
-                  :opened_limit
+    # @overload enabled
+    #   @return [Boolean] Whether ActivityNotification is enabled.
+    # @overload enabled=(value)
+    #   Sets the enabled
+    #   @param [Boolean] enabled The new enabled
+    #   @return [Boolean] Whether ActivityNotification is enabled.
+    attr_accessor :enabled
 
+    # @overload table_name
+    #   @return [String] Table name to store notifications.
+    # @overload table_name=(value)
+    #   Sets the table_name
+    #   @param [String] table_name The new table_name
+    #   @return [String] Table name to store notifications.
+    attr_accessor :table_name
+
+    # @overload email_enabled
+    #   @return [Boolean] Whether activity_notification sends notification email.
+    # @overload email_enabled=(value)
+    #   Sets the email_enabled
+    #   @param [Boolean] email_enabled The new email_enabled
+    #   @return [Boolean] Whether activity_notification sends notification email.
+    attr_accessor :email_enabled
+
+    # @overload mailer_sender
+    #   @return [String] Email address as sender of notification email.
+    # @overload mailer_sender=(value)
+    #   Sets the mailer_sender
+    #   @param [String] mailer_sender The new mailer_sender
+    #   @return [String] Email address as sender of notification email.
+    attr_accessor :mailer_sender
+
+    # @overload mailer
+    #   @return [String] Mailer class for email notification.
+    # @overload mailer=(value)
+    #   Sets the mailer
+    #   @param [String] mailer The new mailer
+    #   @return [String] Mailer class for email notification.
+    attr_accessor :mailer
+
+    # @overload parent_mailer
+    #   @return [String] Base mailer class for email notification.
+    # @overload parent_mailer=(value)
+    #   Sets the parent_mailer
+    #   @param [String] parent_mailer The new parent_mailer
+    #   @return [String] Base mailer class for email notification.
+    attr_accessor :parent_mailer
+
+    # @overload parent_controller
+    #   @return [String] Base controller class for notifications_controller.
+    # @overload parent_controller=(value)
+    #   Sets the parent_controller
+    #   @param [String] parent_controller The new parent_controller
+    #   @return [String] Base controller class for notifications_controller.
+    attr_accessor :parent_controller
+
+    # @overload opened_limit
+    #   @return [Integer] Default limit to query for opened notifications.
+    # @overload opened_limit=(value)
+    #   Sets the opened_limit
+    #   @param [Integer] opened_limit The new opened_limit
+    #   @return [Integer] Default limit to query for opened notifications.
+    attr_accessor :opened_limit
+
+    # Initialize configuration for ActivityNotification.
+    # These configuration can be overriden in initializer.
+    # @return [Config] A new instance of Config
     def initialize
       @enabled           = true
-      @table_name        = "notifications"
+      @table_name        = 'notifications'
       @email_enabled     = false
       @mailer_sender     = nil
-      @mailer            = "ActivityNotification::Mailer"
+      @mailer            = 'ActivityNotification::Mailer'
       @parent_mailer     = 'ActionMailer::Base'
       @parent_controller = 'ApplicationController'
       @opened_limit      = 10

data/lib/activity_notification/controllers/store_controller.rb

@@ -1,17 +1,22 @@
 module ActivityNotification
   class << self
     # Setter for remembering controller instance
+    #
+    # @param [NotificationsController, NotificationsWithDeviseController] controller Controller instance to set
+    # @return [NotificationsController, NotificationsWithDeviseController]] Controller instance to be set
     def set_controller(controller)
       Thread.current[:activity_notification_controller] = controller
     end
 
     # Getter for accessing the controller instance
+    #
+    # @return [NotificationsController, NotificationsWithDeviseController]] Controller instance to be set
     def get_controller
       Thread.current[:activity_notification_controller]
     end
   end
 
-  # Module included in controllers to allow p_a access to controller instance
+  # Module included in controllers to allow ActivityNotification access to controller instance
   module StoreController
     extend ActiveSupport::Concern
 
@@ -20,11 +25,14 @@ module ActivityNotification
       around_filter :store_controller_for_activity_notification unless respond_to?(:around_action)
     end
 
+    # Sets controller as around action to use controller instance in models or helpers
     def store_controller_for_activity_notification
-      ActivityNotification.set_controller(self)
-      yield
-    ensure
-      ActivityNotification.set_controller(nil)
+      begin
+        ActivityNotification.set_controller(self)
+        yield
+      ensure
+        ActivityNotification.set_controller(nil)
+      end
     end
   end
 end

data/lib/activity_notification/helpers/polymorphic_helpers.rb

@@ -1,25 +1,39 @@
 module ActivityNotification
+  # Provides extension of String class to help polymorphic implementation.
   module PolymorphicHelpers
     extend ActiveSupport::Concern
 
     included do
       class ::String
+        # Convets to model instance.
+        # @return [Object] Model instance
         def to_model_name
           singularize.camelize
         end
-      
+
+        # Convets to model class.
+        # @return [Class] Model class
         def to_model_class
           to_model_name.classify.constantize
         end
-      
+
+        # Convets to singularized model name (resource name).
+        # @return [String] Singularized model name (resource name)
         def to_resource_name
           singularize.underscore
         end
-      
+
+        # Convets to pluralized model name (resources name).
+        # @return [String] Pluralized model name (resources name)
         def to_resources_name
           pluralize.underscore
         end
 
+        # Convets to boolean.
+        # Returns true for 'true', '1', 'yes', 'on' and 't'.
+        # Returns false for 'false', '0', 'no', 'off' and 'f'.
+        # @param [Boolean] default Default value to return when the String is not interpretable
+        # @return [Boolean] Convered boolean value
         def to_boolean(default = nil)
           return true if ['true', '1', 'yes', 'on', 't'].include? self
           return false if ['false', '0', 'no', 'off', 'f'].include? self

data/lib/activity_notification/helpers/view_helpers.rb

@@ -1,9 +1,20 @@
-# Provides a shortcut from views to the rendering method.
 module ActivityNotification
+  # Provides a shortcut from views to the rendering method.
   # Module extending ActionView::Base and adding `render_notification` helper.
   module ViewHelpers
-    # View helper for rendering an notification, calls {ActivityNotification::Notification#render} internally.
-    def render_notification notifications, options = {}
+    # View helper for rendering an notification, calls {Notification#render} internally.
+    # @see Notification#render
+    #
+    # @param [Notification, Array<Notificaion>] Array or single instance of notifications to render
+    # @param [Hash] options Options for rendering notifications
+    # @option options [String, Symbol] :target       (nil)                     Target type name to find template or i18n text
+    # @option options [String]         :partial      ("activity_notification/notifications/#{target}", controller.target_view_path, 'activity_notification/notifications/default') Partial template name
+    # @option options [String]         :partial_root (self.key.gsub('.', '/')) Root path of partial template
+    # @option options [String]         :layout       (nil)                     Layout template name
+    # @option options [String]         :layout_root  ('layouts')               Root path of layout template
+    # @option options [String]         :fallback     (nil)                     Fallback template to use when MissingTemplate is raised. Set :text to use i18n text as fallback.
+    # @return [String] Rendered view or text as string
+    def render_notification(notifications, options = {})
       if notifications.is_a? ActivityNotification::Notification
         notifications.render self, options
       elsif notifications.respond_to?(:map)
@@ -13,92 +24,197 @@ module ActivityNotification
     end
     alias_method :render_notifications, :render_notification
 
-    # View helper for rendering embedded partial template of target's notifications
+    # View helper for rendering on notifications of the target to embedded partial template.
+    # It calls {Notification#render} to prepare view as `content_for :index_content`
+    # and render partial index calling `yield :index_content` internally.
+    # For example, this method can be used for notification index as dropdown in common header.
+    # @todo Show examples
+    #
+    # @param [Object] target Target instance of the rendering notifications
+    # @param [Hash] options Options for rendering notifications
+    # @option options [String, Symbol] :target               (nil)       Target type name to find template or i18n text
+    # @option options [String]         :partial_root         ("activity_notification/notifications/#{target.to_resources_name}", 'activity_notification/notifications/default') Root path of partial template
+    # @option options [String]         :notification_partial ("activity_notification/notifications/#{target.to_resources_name}", controller.target_view_path, 'activity_notification/notifications/default') Partial template name of the notification index content
+    # @option options [String]         :layout_root          ('layouts') Root path of layout template
+    # @option options [String]         :notification_layout  (nil)       Layout template name of the notification index content
+    # @option options [String]         :fallback             (nil)       Fallback template to use when MissingTemplate is raised. Set :text to use i18n text as fallback.
+    # @option options [String]         :partial              ('index')   Partial template name of the partial index
+    # @option options [String]         :layout               (nil)       Layout template name of the partial index
+    # @return [String] Rendered view or text as string
     def render_notification_of target, options = {}
       return unless target.is_a? ActivityNotification::Target
 
-      partial_path = options.delete(:partial) || "index"
-      partial_root = options[:partial_root] ||
-                         "activity_notification/notifications/#{target.to_resources_name}"
-      partial      = select_path(partial_path, partial_root)
-      layout       = options[:layout].present? ?
-                       select_path(options.delete(:layout), (options[:layout_root] || "layouts")) :
-                       nil
-      locals       = (options[:locals] || {}).merge(target: target)
-
       # Prepare content for notifications index
-      notification_options = options.merge\
-                               target:  target.to_resources_name, 
-                               partial: options[:notification_partial], 
-                               layout:  options[:notification_layout]
-      case options[:index_content]
-      when :simple
-        notification_index = target.notification_index
-      when :none
-      else
-        notification_index = target.notification_index_with_attributes
-      end
-
-      if notification_index.present?
-        content_for :notification_index do
-          @target = target
-          begin
-            render_notification notification_index, notification_options
-          rescue ActionView::MissingTemplate
-            notification_options.delete(:target)
-            render_notification notification_index, notification_options
-          end
+      notification_options = options.merge target: target.to_resources_name, 
+                               partial: options[:notification_partial], layout: options[:notification_layout]
+      notification_index =
+        case options[:index_content]
+        when :simple then target.notification_index
+        when :none   then target.notifications.none
+        else              target.notification_index_with_attributes
         end
-      end
+      prepare_content_for(target, notification_index, notification_options)
 
       # Render partial index
-      begin
-        render options.merge(partial: partial, layout: layout, locals: locals)
-      rescue ActionView::MissingTemplate
-        partial_root = "activity_notification/notifications/default"
-        partial      = select_path(partial_path, partial_root)
-        render options.merge(partial: partial, layout: layout, locals: locals)
-      end
+      render_partial_index(target, options)
     end
     alias_method :render_notifications_of, :render_notification_of
 
-    # Url helper methods
-    #TODO Is there any other better solution?
-    #TODO Must handle devise namespace
+    # Returns notification_path for the notification
+    #
+    # @param [Notification] notification Notification instance
+    # @param [Hash] params Request parameters
+    # @return [String] notification_path for the notification
+    # @todo Needs any other better implementation
+    # @todo Must handle devise namespace
     def notification_path_for(notification, params = {})
       send("#{notification.target.to_resource_name}_notification_path", notification.target, notification, params)
     end
 
+    # Returns move_notification_path for the target of specified notification
+    #
+    # @param [Notification] notification Notification instance
+    # @param [Hash] params Request parameters
+    # @return [String] move_notification_path for the target
+    # @todo Needs any other better implementation
+    # @todo Must handle devise namespace
     def move_notification_path_for(notification, params = {})
       send("move_#{notification.target.to_resource_name}_notification_path", notification.target, notification, params)
     end
 
+    # Returns open_notification_path for the target of specified notification
+    #
+    # @param [Notification] notification Notification instance
+    # @param [Hash] params Request parameters
+    # @return [String] open_notification_path for the target
+    # @todo Needs any other better implementation
+    # @todo Must handle devise namespace
     def open_notification_path_for(notification, params = {})
       send("open_#{notification.target.to_resource_name}_notification_path", notification.target, notification, params)
     end
 
+    # Returns open_all_notifications_path for the target of specified notification
+    #
+    # @param [Notification] notification Notification instance
+    # @param [Hash] params Request parameters
+    # @return [String] open_all_notifications_path for the target
+    # @todo Needs any other better implementation
+    # @todo Must handle devise namespace
     def open_all_notifications_path_for(target, params = {})
       send("open_all_#{target.to_resource_name}_notifications_path", target, params)
     end
 
+    # Returns notification_url for the target of specified notification
+    #
+    # @param [Notification] notification Notification instance
+    # @param [Hash] params Request parameters
+    # @return [String] notification_url for the target
+    # @todo Needs any other better implementation
+    # @todo Must handle devise namespace
     def notification_url_for(notification, params = {})
       send("#{notification.target.to_resource_name}_notification_url", notification.target, notification, params)
     end
 
+    # Returns move_notification_url for the target of specified notification
+    #
+    # @param [Notification] notification Notification instance
+    # @param [Hash] params Request parameters
+    # @return [String] move_notification_url for the target
+    # @todo Needs any other better implementation
+    # @todo Must handle devise namespace
     def move_notification_url_for(notification, params = {})
       send("move_#{notification.target.to_resource_name}_notification_url", notification.target, notification, params)
     end
 
+    # Returns open_notification_url for the target of specified notification
+    #
+    # @param [Notification] notification Notification instance
+    # @param [Hash] params Request parameters
+    # @return [String] open_notification_url for the target
+    # @todo Needs any other better implementation
+    # @todo Must handle devise namespace
     def open_notification_url_for(notification, params = {})
       send("open_#{notification.target.to_resource_name}_notification_url", notification.target, notification, params)
     end
 
+    # Returns open_all_notifications_url for the target of specified notification
+    #
+    # @param [Notification] notification Notification instance
+    # @param [Hash] params Request parameters
+    # @return [String] open_all_notifications_url for the target
+    # @todo Needs any other better implementation
+    # @todo Must handle devise namespace
     def open_all_notifications_url_for(target, params = {})
       send("open_all_#{target.to_resource_name}_notifications_url", target, params)
     end
 
+
     private
 
+      # Prepare content for notification index
+      # @api private
+      #
+      # @param [Object] target Notification target instance
+      # @param [Array<Notificaion>] notification_index Array notification index
+      # @param [Hash] params Option parameter to send render_notification
+      def prepare_content_for(target, notification_index, params)
+        content_for :notification_index do
+          @target = target
+          begin
+            render_notification notification_index, params
+          rescue ActionView::MissingTemplate
+            params.delete(:target)
+            render_notification notification_index, params
+          end
+        end
+      end
+
+      # Render partial index of notifications
+      # @api private
+      #
+      # @param [Object] target Notification target instance
+      # @param [Hash] params Option parameter to send render
+      # @return [String] Rendered partial index view as string
+      def render_partial_index(target, params)
+        index_path = params.delete(:partial)
+        partial    = partial_index_path(target, index_path, params[:partial_root])
+        layout     = layout_path(params.delete(:layout), params[:layout_root])
+        locals     = (params[:locals] || {}).merge(target: target)
+        begin
+          render params.merge(partial: partial, layout: layout, locals: locals)
+        rescue ActionView::MissingTemplate
+          partial = partial_index_path(target, index_path, 'activity_notification/notifications/default')
+          render params.merge(partial: partial, layout: layout, locals: locals)
+        end
+      end
+
+      # Returns partial index path from options
+      # @api private
+      #
+      # @param [Object] target Notification target instance
+      # @param [String] path Partial index template name
+      # @param [String] root Root path of partial index template
+      # @return [String] Partial index template path
+      def partial_index_path(target, path = nil, root = nil)
+        path ||= 'index'
+        root ||= "activity_notification/notifications/#{target.to_resources_name}"
+        select_path(path, root)
+      end
+
+      # Returns layout path from options
+      # @api private
+      #
+      # @param [String] path Layout template name
+      # @param [String] root Root path of layout template
+      # @return [String] Layout template path
+      def layout_path(path = nil, root = nil)
+        path.nil? and return
+        root ||= 'layouts'
+        select_path(path, root)
+      end
+
+      # Select template path
+      # @api private
       def select_path(path, root)
         [root, path].map(&:to_s).join('/')
       end