activity_notification 0.0.9 → 0.0.10

data/lib/activity_notification/roles/acts_as_notifier.rb

@@ -1,8 +1,11 @@
 module ActivityNotification
+  # Manages to add all required configurations to notifier models of notification.
   module ActsAsNotifier
     extend ActiveSupport::Concern
 
     class_methods do
+      # Adds required configurations to notifier models.
+      # @return [nil] nil
       def acts_as_notifier
         include Notifier
       end

data/lib/activity_notification/roles/acts_as_target.rb

@@ -1,8 +1,76 @@
 module ActivityNotification
+  # Manages to add all required configurations to target models of notification.
   module ActsAsTarget
     extend ActiveSupport::Concern
 
     class_methods do
+      # Adds required configurations to notifiable models.
+      #
+      # == Parameters:
+      # * :email
+      #   * Email address to send notification email.
+      #     This is a necessary option when you enables email notification.
+      # @example Simply use :email field
+      #   class User < ActiveRecord::Base
+      #     validates :email, presence: true
+      #     acts_as_target email: :email
+      #   end
+      #
+      # * :email_allowed
+      #   * Whether activity_notification sends notification email to this target.
+      #     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 Always enable email notification for this target
+      #   class User < ActiveRecord::Base
+      #     acts_as_target email: :email, email_allowed: true
+      #   end
+      # @example Use confirmed_at of devise field to decide whether activity_notification sends notification email to this user
+      #   class User < ActiveRecord::Base
+      #     acts_as_target email: :email, email_allowed: :confirmed_at
+      #   end
+      #
+      # * :devise_resource
+      #   * Integrated resource with devise authentication.
+      #     This parameter is a optional since `self` is used as default value.
+      #     You also have to configure routing for devise inroutes.rb
+      # @example No :devise_resource is needed when notification target is the same as authenticated resource
+      #   # config/routes.rb
+      #   devise_for :users
+      #   notify_to :users
+      #
+      #   # app/models/user.rb
+      #   class User < ActiveRecord::Base
+      #     devise :database_authenticatable, :registerable, :confirmable
+      #     acts_as_target email: :email, email_allowed: :confirmed_at
+      #   end
+      #
+      # @example Send Admin model and use associated User model with devise authentication
+      #   # config/routes.rb
+      #   devise_for :users
+      #   notify_to :admins, with_devise: :users
+      #
+      #   # app/models/user.rb
+      #   class User < ActiveRecord::Base
+      #     devise :database_authenticatable, :registerable, :confirmable
+      #   end
+      #
+      #   # app/models/admin.rb
+      #   class Admin < ActiveRecord::Base
+      #     belongs_to :user
+      #     validates :user, presence: true
+      #     acts_as_notification_target email: :email,
+      #       email_allowed: ->(admin, key) { admin.user.confirmed_at.present? },
+      #       devise_resource: :user
+      #   end
+      #
+      # @param [Symbol] target_type Type of notification target as symbol
+      # @param [Hash] options Options for notifiable model configuration
+      # @option options [Symbol, Proc, Array]   :email           (nil) Email address to send notification email
+      # @option options [Symbol, Proc, Object]  :email_allowed   (ActivityNotification.config.email_enabled) Whether activity_notification sends notification email to this target
+      # @option options [Symbol, Proc, Object]  :devise_resource (nil) Integrated resource with devise authentication
+      # @return [Hash] Configured parameters as target model
       def acts_as_target(options = {})
         include Target
         available_target_options.map { |key|
@@ -13,6 +81,8 @@ module ActivityNotification
       end
       alias_method :acts_as_notification_target, :acts_as_target
 
+      # Returns array of available target options in acts_as_target.
+      # @return [Array<Symbol>] Array of available target options
       def available_target_options
         [:email, :email_allowed, :devise_resource].freeze
       end

data/lib/activity_notification/version.rb

@@ -1,3 +1,3 @@
 module ActivityNotification
-  VERSION = "0.0.9"
+  VERSION = "0.0.10"
 end

data/lib/generators/activity_notification/active_record/migration_generator.rb

@@ -2,7 +2,9 @@ require 'rails/generators/active_record'
 
 module ActivityNotification
   module Generators
-    # Migration generator that creates migration file from template
+    # Migration generator to create migration files from templates.
+    # @example Run migration generator
+    #   rails generate activity_notification:migration
     class MigrationGenerator < ActiveRecord::Generators::Base
       source_root File.expand_path("../../../templates/active_record", __FILE__)
 

data/lib/generators/activity_notification/controllers_generator.rb

@@ -2,6 +2,9 @@ require 'rails/generators/base'
 
 module ActivityNotification
   module Generators
+    # Controller generator to create customizable controller files from templates.
+    # @example Run controller generator for users as target
+    #   rails generate activity_notification:controllers users
     class ControllersGenerator < Rails::Generators::Base
       CONTROLLERS = ['notifications', 'notifications_with_devise'].freeze
 
@@ -27,6 +30,7 @@ module ActivityNotification
       class_option :controllers, aliases: "-c", type: :array,
         desc: "Select specific controllers to generate (#{CONTROLLERS.join(', ')})"
 
+      # Creates controller files in application directory
       def create_controllers
         @target_prefix = target.blank? ? '' : (target.camelize + '::')
         controllers = options[:controllers] || CONTROLLERS
@@ -36,6 +40,7 @@ module ActivityNotification
         end
       end
 
+      # Shows readme to console
       def show_readme
         readme "README" if behavior == :invoke
       end

data/lib/generators/activity_notification/install_generator.rb

@@ -2,16 +2,18 @@ require 'rails/generators/base'
 require 'securerandom'
 
 module ActivityNotification
-  module Generators
-
+  module Generators #:nodoc:
+    # Install generator to copy initializer and locale file to rails application.
+    # @example Run install generator
+    #   rails generate activity_notification:install
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates", __FILE__)
 
       desc "Creates a ActivityNotification initializer and copy locale files to your application."
       class_option :orm
 
+      # Copies initializer file in application directory
       def copy_initializer
-        
         #TODO suport other orm e.g. mongoid
         unless options[:orm] == :active_record
           raise TypeError, <<-ERROR.strip_heredoc
@@ -29,10 +31,12 @@ module ActivityNotification
         template "activity_notification.rb", "config/initializers/activity_notification.rb"
       end
 
+      # Copies locale files in application directory
       def copy_locale
         template "locales/en.yml", "config/locales/activity_notification.en.yml"
       end
 
+      # Shows readme to console
       def show_readme
         readme "README" if behavior == :invoke
       end

data/lib/generators/activity_notification/models/notification_generator.rb

@@ -2,13 +2,15 @@ require 'rails/generators/active_record'
 
 module ActivityNotification
   module Generators
-    # Notification generator that creates notification model file from template
+    # Notification generator to create customizable notification model from templates.
+    # @example Run notification generator to create customizable notification model
+    #   rails generate activity_notification:notification
     class NotificationGenerator < ActiveRecord::Generators::Base
       source_root File.expand_path("../../../templates/notification", __FILE__)
 
       argument :name, type: :string, default: 'Notification'
 
-      # Create model in application directory
+      # Create notification model in application directory
       def create_models
         @model_name = name
         template 'notification.rb', "app/models/#{name.underscore}.rb"

data/lib/generators/activity_notification/views_generator.rb

@@ -2,8 +2,17 @@ require 'rails/generators/base'
 
 module ActivityNotification
   module Generators
+    # View generator to copy customizable view files to rails application.
     # Include this module in your generator to generate ActivityNotification views.
     # `copy_views` is the main method and by default copies all views of ActivityNotification.
+    # @example Run view generator to create customizable default views for all targets
+    #   rails generate activity_notification:views
+    # @example Run view generator to create views for users as the specified target
+    #   rails generate activity_notification:views users
+    # @example Run view generator to create only notification views
+    #   rails generate activity_notification:views -v notifications
+    # @example Run view generator to create only notification email views
+    #   rails generate activity_notification:views -v mailer
     class ViewsGenerator < Rails::Generators::Base
       VIEWS = [:notifications, :mailer].freeze
 
@@ -16,6 +25,7 @@ module ActivityNotification
         desc: "Select specific view directories to generate (notifications, mailer)"
       public_task :copy_views
 
+      # Copies view files in application directory
       def copy_views
         target_views = options[:views] || VIEWS
         target_views.each do |directory|
@@ -25,14 +35,24 @@ module ActivityNotification
 
       protected
 
+        # Copies view files to target directory
+        # @api protected
+        # @param [String] name Set name of views (notifications or mailer)
+        # @param [String] _target_path Target path to create views
         def view_directory(name, _target_path = nil)
           directory "#{name.to_s}/default", _target_path || "#{target_path}/#{name}/#{plural_target || :default}"
         end
   
+        # Gets target_path from an argument or default value
+        # @api protected
+        # @return [String ] target_path from an argument or default value
         def target_path
           @target_path ||= "app/views/activity_notification"
         end
   
+        # Gets plural_target from target argument or default value
+        # @api protected
+        # @return [String] target_path from target argument or default value
         def plural_target
           @plural_target ||= target.presence && target.to_s.underscore.pluralize
         end

data/spec/concerns/apis/notification_api_spec.rb

@@ -22,7 +22,7 @@ shared_examples_for :notification_api do
       expect(@user_2.notifications.count).to eq(0)
     end
 
-    describe "#notify" do
+    describe ".notify" do
       it "returns array of created notifications" do
         notifications = described_class.notify(:users, @comment_2)
         expect(notifications).to be_a Array
@@ -72,7 +72,7 @@ shared_examples_for :notification_api do
       end
     end
 
-    describe "#notify_all" do
+    describe ".notify_all" do
       it "returns array of created notifications" do
         notifications = described_class.notify_all([@author_user, @user_1], @comment_2)
         expect(notifications).to be_a Array
@@ -117,7 +117,7 @@ shared_examples_for :notification_api do
       end
     end
 
-    describe "#notify_to" do
+    describe ".notify_to" do
       it "returns reated notification" do
         notification = described_class.notify_to(@user_1, @comment_2)
         validate_expected_notification(notification, @user_1, @comment_2)
@@ -302,10 +302,10 @@ shared_examples_for :notification_api do
       end
     end
 
-    describe "#open_all_of" do
+    describe ".open_all_of" do
       before do
-        described_class.notify_to(@user_1, @comment_2)
-        described_class.notify_to(@user_1, @comment_2)
+        described_class.notify_to(@user_1, @article, group: @article, key: 'key.1')
+        described_class.notify_to(@user_1, @comment_2, group: @comment_2, key: 'key.2')
         expect(@user_1.notifications.unopened_only.count).to eq(2)
         expect(@user_1.notifications.opened_only!.count).to eq(0)
       end
@@ -325,9 +325,58 @@ shared_examples_for :notification_api do
         expect(@user_1.notifications.unopened_only.count).to eq(2)
         expect(@user_1.notifications.opened_only!.count).to eq(0)
       end
+
+      it "opens all notification with current time" do
+        expect(@user_1.notifications.first.opened_at).to be_nil
+        Timecop.freeze(DateTime.now)
+        described_class.open_all_of(@user_1)
+        expect(@user_1.notifications.first.opened_at.to_i).to eq(DateTime.now.to_i)
+        Timecop.return
+      end
+
+      context "with opened_at option" do
+        it "opens all notification with specified time" do
+          expect(@user_1.notifications.first.opened_at).to be_nil
+          opened_at = DateTime.now - 1.months
+          described_class.open_all_of(@user_1, opened_at: opened_at)
+          expect(@user_1.notifications.first.opened_at.to_i).to eq(opened_at.to_i)
+        end
+      end
+
+      context 'with filtered_by_type options' do
+        it "opens filtered notifications only" do
+          described_class.open_all_of(@user_1, { filtered_by_type: @comment_2.to_class_name })
+          expect(@user_1.notifications.unopened_only.count).to eq(1)
+          expect(@user_1.notifications.opened_only!.count).to eq(1)
+        end
+      end
+
+      context 'with filtered_by_group options' do
+        it "opens filtered notifications only" do
+          described_class.open_all_of(@user_1, { filtered_by_group: @comment_2 })
+          expect(@user_1.notifications.unopened_only.count).to eq(1)
+          expect(@user_1.notifications.opened_only!.count).to eq(1)
+        end
+      end
+
+      context 'with filtered_by_group_type and :filtered_by_group_id options' do
+        it "opens filtered notifications only" do
+          described_class.open_all_of(@user_1, { filtered_by_group_type: 'Comment', filtered_by_group_id: @comment_2.id.to_s })
+          expect(@user_1.notifications.unopened_only.count).to eq(1)
+          expect(@user_1.notifications.opened_only!.count).to eq(1)
+        end
+      end
+
+      context 'with filtered_by_key options' do
+        it "opens filtered notifications only" do
+          described_class.open_all_of(@user_1, { filtered_by_key: 'key.2' })
+          expect(@user_1.notifications.unopened_only.count).to eq(1)
+          expect(@user_1.notifications.opened_only!.count).to eq(1)
+        end
+      end
     end
 
-    describe "#group_member_exists?" do
+    describe ".group_member_exists?" do
       context "when specified notifications have any group members" do
         let(:owner_notifications) do
           target       = create(:confirmed_user)
@@ -337,10 +386,15 @@ shared_examples_for :notification_api do
           target.notifications.group_owners_only
         end
 
-        it "returns true" do
+        it "returns true for DB query" do
           expect(described_class.group_member_exists?(owner_notifications))
             .to be_truthy
         end
+
+        it "returns true for Array" do
+          expect(described_class.group_member_exists?(owner_notifications.to_a))
+            .to be_truthy
+        end
       end
 
       context "when specified notifications have no group members" do
@@ -358,7 +412,7 @@ shared_examples_for :notification_api do
       end
     end
 
-    describe "#available_options" do
+    describe ".available_options" do
       it "returns list of available options in notify api" do
         expect(described_class.available_options)
           .to eq([:key, :group, :parameters, :notifier, :send_email, :send_later])
@@ -367,7 +421,7 @@ shared_examples_for :notification_api do
   end
 
   describe "as private class methods" do
-    describe "#store_notification" do
+    describe ".store_notification" do
       it "is defined as private method" do
         expect(described_class.respond_to?(:store_notification)).to       be_falsey
         expect(described_class.respond_to?(:store_notification, true)).to be_truthy
@@ -430,38 +484,52 @@ shared_examples_for :notification_api do
           Timecop.return
         end
 
-        #TODO
-        # it "open group member notifications with current time" do
-          # group_member = create(test_class_name, group_owner: test_instance)
-          # expect(group_member.opened_at.blank?).to be_truthy
-          # Timecop.freeze(DateTime.now)
-          # test_instance.open!
-          # group_member = group_member.reload
-          # expect(group_member.opened_at.blank?).to be_falsey
-          # expect(group_member.opened_at).to        eq(DateTime.now)
-          # Timecop.return
-        # end
+        it "open group member notifications with current time" do
+          group_member = create(test_class_name, group_owner: test_instance)
+          expect(group_member.opened_at.blank?).to be_truthy
+          Timecop.freeze(DateTime.now)
+          test_instance.open!
+          group_member = group_member.reload
+          expect(group_member.opened_at.blank?).to be_falsey
+          expect(group_member.opened_at.to_i).to   eq(DateTime.now.to_i)
+          Timecop.return
+        end
       end
 
-      context "with an argument" do
+      context "with opened_at option" do
         it "open notification with specified time" do
           expect(test_instance.opened_at.blank?).to be_truthy
-          datetime = DateTime.now - 1.months
-          test_instance.open!(datetime)
+          opened_at = DateTime.now - 1.months
+          test_instance.open!(opened_at: opened_at)
           expect(test_instance.opened_at.blank?).to be_falsey
-          expect(test_instance.opened_at).to        eq(datetime)
+          expect(test_instance.opened_at).to        eq(opened_at)
+        end
+
+        it "open group member notifications with specified time" do
+          group_member = create(test_class_name, group_owner: test_instance)
+          expect(group_member.opened_at.blank?).to be_truthy
+          opened_at = DateTime.now - 1.months
+          test_instance.open!(opened_at: opened_at)
+          group_member = group_member.reload
+          expect(group_member.opened_at.blank?).to be_falsey
+          expect(group_member.opened_at.to_i).to   eq(opened_at.to_i)
+        end
+      end
+
+      context "with false as with_members" do
+        it "does not open group member notifications" do
+          group_member = create(test_class_name, group_owner: test_instance)
+          expect(group_member.opened_at.blank?).to be_truthy
+          opened_at = DateTime.now - 1.months
+          test_instance.open!(with_members: false)
+          group_member = group_member.reload
+          expect(group_member.opened_at.blank?).to be_truthy
         end
 
-        #TODO
-        # it "open group member notifications with current time" do
-          # group_member = create(test_class_name, group_owner: test_instance)
-          # expect(group_member.opened_at.blank?).to be_truthy
-          # datetime = DateTime.now - 1.months
-          # test_instance.open!(datetime)
-          # group_member = group_member.reload
-          # expect(group_member.opened_at.blank?).to be_falsey
-          # expect(group_member.opened_at).to        eq(datetime)
-        # end
+        it "returns the number of opened notification records" do
+          create(test_class_name, group_owner: test_instance, opened_at: nil)
+          expect(test_instance.open!(with_members: false)).to eq(1)
+        end
       end
     end
 
@@ -624,7 +692,8 @@ shared_examples_for :notification_api do
 
     describe "#notifiable_path" do
       it "returns notifiable.notifiable_path" do
-        expect(test_instance.notifiable_path).to eq(test_instance.notifiable.notifiable_path(test_instance.target_type))
+        expect(test_instance.notifiable_path)
+          .to eq(test_instance.notifiable.notifiable_path(test_instance.target_type, test_instance.key))
       end
     end
   end