activity_notification 0.0.9 → 0.0.10

data/lib/activity_notification/rails/routes.rb

@@ -2,61 +2,61 @@ require "active_support/core_ext/object/try"
 require "active_support/core_ext/hash/slice"
 
 module ActionDispatch::Routing
+  # Extended ActionDispatch::Routing::Mapper implementation to add routing method of ActivityNotification.
   class Mapper
-    # Includes notify_to method for routes.
-    # This method is responsible to generate all needed routes for activity_notification
-    #
-    # ==== Examples
-    #
-    #   notify_to :users
-    #   notify_to :users, with_devise: :users
-    #   notify_to :users, with_devise: :users, only: [:open, :open_all, :move]
+    # Includes notify_to method for routes, which is responsible to generate all necessary routes for activity_notification.
     #
     # When you have an User model configured as a target (e.g. defined acts_as_target),
-    # you can creat this inside your routes:
-    #
+    # you can create as follows in your routes:
     #   notify_to :users
-    #
     # This method creates the needed routes:
+    #   # Notification routes
+    #     user_notifications          GET    /users/:user_id/notifications(.:format)
+    #       { controller:"activity_notification/notifications", action:"index", target_type:"users" }
+    #     user_notification           GET    /users/:user_id/notifications/:id(.:format)
+    #       { controller:"activity_notification/notifications", action:"show", target_type:"users" }
+    #     user_notification           DELETE /users/:user_id/notifications/:id(.:format)
+    #       { controller:"activity_notification/notifications", action:"destroy", target_type:"users" }
+    #     open_all_user_notifications POST   /users/:user_id/notifications/open_all(.:format)
+    #       { controller:"activity_notification/notifications", action:"open_all", target_type:"users" }
+    #     move_user_notification      POST   /users/:user_id/notifications/:id/move(.:format)
+    #       { controller:"activity_notification/notifications", action:"move", target_type:"users" }
+    #     open_user_notification      POST   /users/:user_id/notifications/:id/open(.:format)
+    #       { controller:"activity_notification/notifications", action:"open", target_type:"users" }
     #
-    #  # Notification routes
-    #          user_notifications GET    /users/:user_id/notifications(.:format)
-    #                                    {controller:"activity_notification/notifications", action:"index", target_type:"users"}
-    #           user_notification GET    /users/:user_id/notifications/:id(.:format)
-    #                                    {controller:"activity_notification/notifications", action:"show", target_type:"users"}
-    #           user_notification DELETE /users/:user_id/notifications/:id(.:format)
-    #                                    {controller:"activity_notification/notifications", action:"destroy", target_type:"users"}
-    # open_all_user_notifications POST   /users/:user_id/notifications/open_all(.:format)
-    #                                      {controller:"activity_notification/notifications", action:"open_all", target_type:"users"}
-    #      move_user_notification POST   /users/:user_id/notifications/:id/move(.:format)
-    #                                      {controller:"activity_notification/notifications", action:"move", target_type:"users"}
-    #      open_user_notification POST   /users/:user_id/notifications/:id/open(.:format)
-    #                                      {controller:"activity_notification/notifications", action:"open", target_type:"users"}
-    #
-    # When you use devise for authentication and you want make notification target assciated with devise,
-    # you can creat this inside your routes:
-    #
-    #   notify_to :users, with_devise: true
-    #
+    # When you use devise authentication and you want make notification targets assciated with devise,
+    # you can create as follows in your routes:
+    #   notify_to :users, with_devise: :users
     # This with_devise option creates the needed routes assciated with devise authentication:
+    #   # Notification with devise routes
+    #     user_notifications          GET    /users/:user_id/notifications(.:format)
+    #       { controller:"activity_notification/notifications_with_devise", action:"index", target_type:"users", devise_type:"users" }
+    #     user_notification           GET    /users/:user_id/notifications/:id(.:format)
+    #       { controller:"activity_notification/notifications_with_devise", action:"show", target_type:"users", devise_type:"users" }
+    #     user_notification           DELETE /users/:user_id/notifications/:id(.:format)
+    #       { controller:"activity_notification/notifications_with_devise", action:"destroy", target_type:"users", devise_type:"users" }
+    #     open_all_user_notifications POST   /users/:user_id/notifications/open_all(.:format)
+    #       { controller:"activity_notification/notifications_with_devise", action:"open_all", target_type:"users", devise_type:"users" }
+    #     move_user_notification      POST   /users/:user_id/notifications/:id/move(.:format)
+    #       { controller:"activity_notification/notifications_with_devise", action:"move", target_type:"users", devise_type:"users" }
+    #     open_user_notification      POST   /users/:user_id/notifications/:id/open(.:format)
+    #       { controller:"activity_notification/notifications_with_devise", action:"open", target_type:"users", devise_type:"users" }
     #
-    #  # Notification with devise routes
-    #          user_notifications GET    /users/:user_id/notifications(.:format)
-    #                                    {controller:"activity_notification/notifications_with_devise", action:"index", devise_type:"users", target_type:"users"}
-    #           user_notification GET    /users/:user_id/notifications/:id(.:format)
-    #                                    {controller:"activity_notification/notifications_with_devise", action:"show", devise_type:"users", target_type:"users"}
-    #           user_notification DELETE /users/:user_id/notifications/:id(.:format)
-    #                                    {controller:"activity_notification/notifications_with_devise", action:"destroy", devise_type:"users", target_type:"users"}
-    # open_all_user_notifications POST   /users/:user_id/notifications/open_all(.:format)
-    #                                      {controller:"activity_notification/notifications_with_devise", action:"open_all", devise_type:"users", target_type:"users"}
-    #      move_user_notification POST   /users/:user_id/notifications/:id/move(.:format)
-    #                                      {controller:"activity_notification/notifications_with_devise", action:"move", devise_type:"users", target_type:"users"}
-    #      open_user_notification POST   /users/:user_id/notifications/:id/open(.:format)
-    #                                      {controller:"activity_notification/notifications_with_devise", action:"open", devise_type:"users", target_type:"users"}
-    #
-    # ==== Options
-    #TODO add document for options
+    # @example Define notify_to in config/routes.rb
+    #   notify_to :users
+    # @example Define notify_to with options
+    #   notify_to :users, only: [:open, :open_all, :move]
+    # @example Integrated with Devise authentication
+    #   notify_to :users, with_devise: :users
     #
+    # @overload notify_to(*resources, *options)
+    #   @param          [Symbol] resources Resources to notify
+    #   @option options [Symbol] :with_devise Devise resources name for devise integration. Devise integration will be enabled by this option.
+    #   @option options [String] :controller  controller option as resources routing
+    #   @option options [Symbol] :as          as option as resources routing
+    #   @option options [Array]  :only        only option as resources routing
+    #   @option options [Array]  :except      except option as resources routing
+    # @return [ActionDispatch::Routing::Mapper] Routing mapper instance
     def notify_to(*resources)
       options = resources.extract_options!
       
@@ -65,13 +65,14 @@ module ActionDispatch::Routing
       if (with_devise = options.delete(:with_devise)).present?
         options[:controller] ||= "activity_notification/notifications_with_devise"
         options[:as]         ||= "notifications"
-        #TODO check device configuration in model
+        #TODO check devise configuration in model
         devise_defaults        = { devise_type: with_devise.to_s }
       else
         options[:controller] ||= "activity_notification/notifications"
       end
       options[:except]       ||= []
       options[:except].concat( [:new, :create, :edit, :update] )
+      notification_resources   = options[:model] || :notifications
 
       #TODO other options
       # :as, :path_prefix, :path_names ...
@@ -79,7 +80,7 @@ module ActionDispatch::Routing
       resources.each do |resource|
         self.resources resource, only: :none do
           options[:defaults] = (devise_defaults || {}).merge({ target_type: resource.to_s })
-          self.resources :notifications, options do
+          self.resources notification_resources, options do
             collection do
               post :open_all unless ignore_path?(:open_all, options)
             end
@@ -91,6 +92,7 @@ module ActionDispatch::Routing
         end
       end
 
+      self
     end
 
     private

data/lib/activity_notification/renderable.rb

@@ -1,10 +1,15 @@
 module ActivityNotification
   # Provides logic for rendering notifications.
-  # Handles both i18n strings support and smart partials rendering (different templates per notification key).
-  # Deeply uses PublicActivity as reference
+  # Handles both i18n strings support and smart partials rendering (different templates per the notification key).
+  # This module deeply uses PublicActivity gem as reference.
   module Renderable
     # Virtual attribute returning text description of the notification
     # using the notification's key to translate using i18n.
+    #
+    # @param [Hash] params Parameters for rendering notification text
+    # @option params [String] :target Target type name to use as i18n text key
+    # @option params [Hash] others Parameters to be reffered in i18n text
+    # @return [String] Rendered text
     def text(params = {})
       k = key.split('.')
       k.unshift('notification') if k.first != 'notification'
@@ -21,20 +26,17 @@ module ActivityNotification
 
     # Renders notification from views.
     #
-    # @param [ActionView::Base] context
-    # @return [nil] nil
-    #
     # The preferred way of rendering notifications is
     # to provide a template specifying how the rendering should be happening.
-    # However, you can choose using _I18n_ based approach when developing
+    # However, you can choose using _i18n_ based approach when developing
     # an application that supports plenty of languages.
     #
-    # If partial view exists that matches the "key" attribute
+    # If partial view exists that matches the "target" type and "key" attribute
     # renders that partial with local variables set to contain both
-    # Activity and activity_parameters (hash with indifferent access).
+    # Notification and notification_parameters (hash with indifferent access).
     #
     # If the partial view does not exist and you wish to fallback to rendering
-    # through the I18n translation, you can do so by passing in a :fallback
+    # through the i18n translation, you can do so by passing in a :fallback
     # parameter whose value equals :text.
     #
     # If you do not want to define a partial view, and instead want to have
@@ -42,48 +44,99 @@ module ActivityNotification
     # value equal to the partial you wish to use when the partial defined
     # by the notification key does not exist.
     #
-    # @example Render a list of all @target's notifications of from a view (erb)
+    # Render a list of all notifications of @target from a view (erb):
     #   <ul>
     #     <% @target.notifications.each do |notification|  %>
-    #       <li><%= render_notification(notification) %></li>
+    #       <li><%= render_notification notification %></li>
     #     <% end %>
     #   </ul>
     #
-    # @example Fallback to the I18n text translation if the view is missing 
+    # Fallback to the i18n text translation if the view is missing:
     #   <ul>
     #     <% @target.notifications.each do |notification|  %>
-    #       <li><%= render_notification(notification, fallback: :text) %></li>
+    #       <li><%= render_notification notification, fallback: :text %></li>
     #     <% end %>
     #   </ul>
     #
-    # @example Fallback to a default view if the view for the current notification key is missing.
-    # The string is the partial name you wish to use.
+    # Fallback to a default view if the view for the current notification key is missing:
     #   <ul>
     #     <% @target.notifications.each do |notification|  %>
-    #       <li><%= render_notification(notification, fallback: 'default') %></li>
+    #       <li><%= render_notification notification, fallback: 'default' %></li>
     #     <% end %>
     #   </ul>
     #
-    # # Layouts
-    #TODO
+    # = Layouts
+    #
+    # You can supply a layout that will be used for notification partials
+    # with :layout param.
+    # Keep in mind that layouts for partials are also partials.
+    #
+    # Supply a layout:
+    #   # in views:
+    #   # All examples look for a layout in app/views/layouts/_notification.erb
+    #   render_notification @notification, layout: "notification"
+    #   render_notification @notification, layout: "layouts/notification"
+    #   render_notification @notification, layout: :notification
+    #
+    #   # app/views/layouts/_notification.erb
+    #   <p><%= notification.created_at %></p>
+    #   <%= yield %>
     #
-    # # Creating a template
+    # == Custom Layout Location
+    # 
+    # You can customize the layout directory by supplying :layout_root
+    # or by using an absolute path.
+    #
+    # Declare custom layout location:
+    #   # Both examples look for a layout in "app/views/custom/_layout.erb"
+    #   render_notification @notification, layout_root: "custom"
+    #   render_notification @notification, layout: "/custom/layout"
+    #
+    # = Creating a template
     #
     # To use templates for formatting how the notification should render,
     # create a template based on target type and notification key, for example:
     #
     # Given a target type users and key _notification.article.create_, create directory tree
-    # _app/views/activity_notifications/users/article/_ and create the _create_ partial there
+    # _app/views/activity_notification/notifications/users/article/_ and create the _create_ partial there
     #
     # Note that if a key consists of more than three parts splitted by commas, your
     # directory structure will have to be deeper, for example:
-    #   notification.article.comments.destroy => app/views/activity_notifications/users/articles/comments/_destroy.html.erb
+    #   notification.article.comment.reply => app/views/activity_notification/notifications/users/article/comment/_reply.html.erb
+    #
+    # == Custom Directory
+    #
+    # You can override the default `activity_notification/notifications/#{target}` template root with the :partial_root parameter.
+    #
+    # Custom template root:
+    #    # look for templates inside of /app/views/custom instead of /app/views/public_directory/activity_notification/notifications/#{target}
+    #    render_notification @notification, partial_root: "custom"
     #
-    # ## Custom Directory
-    #TODO
+    # == Variables in templates
     #
-    # ## Variables in templates
-    #TODO
+    # From within a template there are three variables at your disposal:
+    #
+    # * notification
+    # * controller
+    # * parameters [converted into a HashWithIndifferentAccess]
+    #
+    # Template for key: _notification.article.create_ (erb):
+    #   <p>
+    #     Article <strong><%= parameters[:title] %></strong>
+    #     was posted by <em><%= parameters["author"] %></em>
+    #     <%= distance_of_time_in_words_to_now(notification.created_at) %>
+    #   </p>
+    #
+    # @param [ActionView::Base] context
+    # @param [Hash] params Parameters for rendering notifications
+    # @option params [String, Symbol] :target       (nil)                     Target type name to find template or i18n text
+    # @option params [String]         :partial_root ("activity_notification/notifications/#{target}", controller.target_view_path, 'activity_notification/notifications/default') Partial template name
+    # @option params [String]         :partial      (self.key.gsub('.', '/')) Root path of partial template
+    # @option params [String]         :layout       (nil)                     Layout template name
+    # @option params [String]         :layout_root  ('layouts')               Root path of layout template
+    # @option params [String]         :fallback     (nil)                     Fallback template to use when MissingTemplate is raised. Set :text to use i18n text as fallback.
+    # @option params [Hash]           others                                  Parameters to be set as locals
+    # @return [String] Rendered view or text as string
     def render(context, params = {})
       params[:i18n] and return context.render text: self.text(params)
 
@@ -105,6 +158,12 @@ module ActivityNotification
       end
     end
 
+    # Returns partial path from options
+    #
+    # @param [String] path Partial template name
+    # @param [String] root Root path of partial template
+    # @param [String, Symbol] target Target type name to find template
+    # @return [String] Partial template path
     def partial_path(path = nil, root = nil, target = nil)
       controller = ActivityNotification.get_controller         if ActivityNotification.respond_to?(:get_controller)
       root ||= "activity_notification/notifications/#{target}" if target.present?
@@ -114,27 +173,48 @@ module ActivityNotification
       select_path(path, root)
     end
 
+    # Returns layout path from options
+    #
+    # @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
 
+    # Returns locals parameter for view
+    # There are three variables to be add by method:
+    # * notification
+    # * controller
+    # * parameters [converted into a HashWithIndifferentAccess]
+    #
+    # @param [Hash] params Parameters to add parameters at locals
+    # @return [Hash] locals parameter
     def prepare_locals(params)
       locals = params.delete(:locals) || {}
-
       prepared_parameters = prepare_parameters(params)
       locals.merge\
         notification: self,
+        controller:   ActivityNotification.get_controller,
         parameters:   prepared_parameters
     end
 
+    # Prepares parameters with @prepared_params.
+    # Converted into a HashWithIndifferentAccess.
+    #
+    # @param [Hash] params Parameters to prepare
+    # @return [Hash] Prepared parameters
     def prepare_parameters(params)
       @prepared_params ||= self.parameters.with_indifferent_access.merge(params)
     end
 
+
     private
 
+      # Select template path
+      # @api private
       def select_path(path, root)
         [root, path].map(&:to_s).join('/')
       end

data/lib/activity_notification/roles/acts_as_notifiable.rb

@@ -1,52 +1,125 @@
 module ActivityNotification
+  # Manages to add all required configurations to notifiable models.
   module ActsAsNotifiable
     extend ActiveSupport::Concern
 
     class_methods do
-      # Adds required callbacks for creating and updating notifiable models.
+      # Adds required configurations to notifiable models.
       #
       # == Parameters:
-      # [:targets, :group, :notifier, :parameters, :email_allowed, :notifiable_path]
-      # targets:         Targets to send notification. It it set as ActiveRecord records or array of models.
-      #                  This is a only necessary option. If you do not specify this option, you have to override
-      #                  notification_targets or notification_[plural target type] (e.g. notification_users) method.
+      # * :targets
+      #   * Targets to send notifications.
+      #     It it set as ActiveRecord records or array of models.
+      #     This is a only necessary option.
+      #     If you do not specify this option, you have to override notification_targets
+      #     or notification_[plural target type] (e.g. notification_users) method.
+      # @example Notify to all users
+      #   class Comment < ActiveRecord::Base
+      #     acts_as_notifiable :users, targets: User.all
+      #   end
+      # @example Notify to author and users commented to the article, except comment owner self
+      #   class Comment < ActiveRecord::Base
+      #     belongs_to :article
+      #     belongs_to :user
+      #     acts_as_notifiable :users,
+      #       targets: ->(comment, key) {
+      #         ([comment.article.user] + comment.article.commented_users.to_a - [comment.user]).uniq
+      #       }
+      #   end
       #
-      # group:           Group unit of notifications. Notifications will be bundled by this group (and target, notifiable_type, key).
-      #                  This parameter is a optional.
+      # * :group
+      #   * Group unit of notifications.
+      #     Notifications will be bundled by this group (and target, notifiable_type, key).
+      #     This parameter is a optional.
+      # @example All *unopened* notifications to the same target will be grouped by `article`
+      #   class Comment < ActiveRecord::Base
+      #     belongs_to :article
+      #     acts_as_notifiable :users, targets: User.all, group: :article
+      #   end
       #
-      # notifier:        Notifier of the notification.This will be stored as notifier with notification record.
-      #                  This parameter is a optional.
+      # * :notifier
+      #   * Notifier of the notification.
+      #     This will be stored as notifier with notification record.
+      #     This parameter is a optional.
+      # @example Set comment owner self as notifier
+      #   class Comment < ActiveRecord::Base
+      #     belongs_to :article
+      #     belongs_to :user
+      #     acts_as_notifiable :users, targets: User.all, notifier: :user
+      #   end
       #
-      # parameters:      Parameter to add notification data. This will be stored as parameters with notification record.
-      #                  This parameter is a optional.
+      # * :parameters
+      #   * Additional parameters of the notifications.
+      #     This will be stored as parameters with notification record.
+      #     You can use these additional parameters in your notification view or i18n text.
+      #     This parameter is a optional.
+      # @example Set constant values as additional parameter
+      #   class Comment < ActiveRecord::Base
+      #     acts_as_notifiable :users, targets: User.all, parameters: { default_param: '1' }
+      #   end
+      # @example Set comment body as additional parameter
+      #   class Comment < ActiveRecord::Base
+      #     acts_as_notifiable :users, targets: User.all, parameters: ->(comment, key) { body: comment.body }
+      #   end
       #
-      # email_allowed:   If activity_notification sends notification email to these targets.
-      #                  Specified method or symbol is expected to return true (not nil) or false (nil).
-      #                  This parameter is a optional since default value is false.
-      #                  To use notification email, email_allowed option must return true (not nil) in both of notifiable and target model.
-      #                  This can be also configured default option in initializer.
+      # * :email_allowed
+      #   * Whether activity_notification sends notification email.
+      #     Specified method or symbol is expected to return true (not nil) or false (nil).
+      #     This parameter is a optional since default value is false.
+      #     To use notification email, email_allowed option must return true (not nil) in both of notifiable and target model.
+      #     This can be also configured default option in initializer.
+      # @example Enable email notification for this notifiable model
+      #   class Comment < ActiveRecord::Base
+      #     acts_as_notifiable :users, targets: User.all, email_allowed: true
+      #   end
       #
-      # notifiable_path: Path to redirect from open or move action of notification controller.
-      #                  You can use this notifiable_path as notifiable link in notification view.
-      #                  This parameter is a optional since polymorphic_path is used as default value.
+      # * :notifiable_path
+      #   * Path to redirect from open or move action of notification controller.
+      #     You can also use this notifiable_path as notifiable link in notification view.
+      #     This parameter is a optional since polymorphic_path is used as default value.
+      # @example Redirect to parent article page from comment notifications
+      #   class Comment < ActiveRecord::Base
+      #     belongs_to :article
+      #     acts_as_notifiable :users, targets: User.all, notifiable_path: :article_notifiable_path
+      #
+      #     def article_notifiable_path
+      #       article_path(article)
+      #     end
+      #   end
+      #
+      # @param [Symbol] target_type Type of notification target as symbol
+      # @param [Hash] options Options for notifiable model configuration
+      # @option options [Symbol, Proc, Array]   :targets         (nil)                    Targets to send notifications
+      # @option options [Symbol, Proc, Object]  :group           (nil)                    Group unit of the notifications
+      # @option options [Symbol, Proc, Object]  :notifier        (nil)                    Notifier of the notifications
+      # @option options [Symbol, Proc, Hash]    :parameters      ({})                     Additional parameters of the notifications
+      # @option options [Symbol, Proc, Boolean] :email_allowed   (ActivityNotification.config.email_enabled) Whether activity_notification sends notification email
+      # @option options [Symbol, Proc, String]  :notifiable_path (polymorphic_path(self)) Path to redirect from open or move action of notification controller
+      # @return [Hash] Configured parameters as notifiable model
       def acts_as_notifiable(target_type, options = {})
         include Notifiable
         (
           [:targets, :group, :parameters, :email_allowed].map { |key|
-            options[key] ?
-              [key, self.send("_notification_#{key}".to_sym).store(target_type.to_sym, options.delete(key))] :
-              [nil, nil]
+            assign_parameter(target_type, key, "_notification_#{key}", options)
           }.to_h.merge [:notifier, :notifiable_path].map { |key|
-            options[key] ?
-              [key, self.send("_#{key}".to_sym).store(target_type.to_sym, options.delete(key))] :
-              [nil, nil]
+            assign_parameter(target_type, key, "_#{key}", options)
           }.to_h
-        ).delete_if { |k, v| k.nil? }
+        ).delete_if { |k, _| k.nil? }
       end
 
+      # Returns array of available notifiable options in acts_as_notifiable.
+      # @return [Array<Symbol>] Array of available notifiable options
       def available_notifiable_options
         [:targets, :group, :notifier, :parameters, :email_allowed, :notifiable_path].freeze
       end
+
+      private
+
+        def assign_parameter(target_type, key, field_name, options)
+          options[key] ?
+            [key, self.send(field_name.to_sym).store(target_type.to_sym, options.delete(key))] :
+            [nil, nil]
+        end
     end
   end
 end