activity_notification 1.0.2 → 1.1.0

data/.yardopts

@@ -1,3 +1,6 @@
 --no-private
 --hide-api private
 --plugin activesupport-concern
+--exclude /templates/
+app/**/*.rb
+lib/**/*.rb

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 1.1.0 / 2016-12-18
+[Full Changelog](http://github.com/simukappu/activity_notification/compare/v1.0.2...v1.1.0)
+
+Enhancements:
+
+* Add subscription management framework
+  * Subscription management model and API
+  * Default subscription management controllers, routing and views
+  * Add Subscriber role configuration to Target role
+* Add as_latest_group_member option to batch mailer API
+* Add group_expiry_delay option to notification API
+
+Bug Fixes:
+
+* Fix unserializable error in Target#send_batch_unopened_notification_email since unnecessary options are passed to mailer
+
+Breaking Changes:
+
+* Remove notifiable_type from the argument of overriden method or configured lambda function for Target#batch_notification_email_allowed?
+
 ## 1.0.2 / 2016-11-14
 [Full Changelog](http://github.com/simukappu/activity_notification/compare/v1.0.1...v1.0.2)
 
@@ -19,6 +39,10 @@ Enhancements:
   * Add methods to get notifications for specified target type grouped by targets like `notification_index_map`
 * Arrange default notification email view templates
 
+Breaking Changes:
+
+* Use instance variables @notification.target and @notification.notifiable instead of @target and @notifiable in notification email templates
+
 ## 1.0.0 / 2016-10-06
 [Full Changelog](http://github.com/simukappu/activity_notification/compare/v0.0.10...v1.0.0)
 
@@ -38,6 +62,7 @@ Enhancements:
 * Make default rails version 5.0 and update gem dependency
 
 Breaking Changes:
+
 * Rename `opened_limit` configuration parameter to `opened_index_limit`
   * http://github.com/simukappu/activity_notification/commit/591e53cd8977220f819c11cd702503fc72dd1fd1
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    activity_notification (1.0.2)
+    activity_notification (1.1.0)
       activerecord (>= 4.2.0)
       i18n (>= 0.5.0)
       jquery-rails (>= 3.1.1)
@@ -51,19 +51,19 @@ GEM
       activesupport (>= 3.0)
       railties (>= 3.0)
       rspec-rails (>= 2.2)
-    arel (7.1.2)
+    arel (7.1.4)
     bcrypt (3.1.11)
     builder (3.2.2)
-    bullet (5.4.2)
+    bullet (5.4.3)
       activesupport (>= 3.0.0)
       uniform_notifier (~> 1.10.0)
-    concurrent-ruby (1.0.2)
-    coveralls (0.8.15)
+    concurrent-ruby (1.0.3)
+    coveralls (0.8.17)
       json (>= 1.8, < 3)
       simplecov (~> 0.12.0)
       term-ansicolor (~> 1.3)
       thor (~> 0.19.1)
-      tins (>= 1.6.0, < 2)
+      tins (~> 1.6)
     devise (4.2.0)
       bcrypt (~> 3.0)
       orm_adapter (~> 0.1)
@@ -73,10 +73,10 @@ GEM
     diff-lcs (1.2.5)
     docile (1.1.5)
     erubis (2.7.0)
-    factory_girl (4.7.0)
+    factory_girl (4.8.0)
       activesupport (>= 3.0.0)
-    factory_girl_rails (4.7.0)
-      factory_girl (~> 4.7.0)
+    factory_girl_rails (4.8.0)
+      factory_girl (~> 4.8.0)
       railties (>= 3.0.0)
     globalid (0.3.7)
       activesupport (>= 4.1.0)
@@ -95,13 +95,11 @@ GEM
       mime-types-data (~> 3.2015)
     mime-types-data (3.2016.0521)
     mini_portile2 (2.1.0)
-    minitest (5.9.1)
+    minitest (5.10.1)
     nio4r (1.2.1)
-    nokogiri (1.6.8)
+    nokogiri (1.6.8.1)
       mini_portile2 (~> 2.1.0)
-      pkg-config (~> 1.1.7)
     orm_adapter (0.5.0)
-    pkg-config (1.1.7)
     rack (2.0.1)
     rack-test (0.6.3)
       rack (>= 1.0)
@@ -132,7 +130,7 @@ GEM
       method_source
       rake (>= 0.8.7)
       thor (>= 0.18.1, < 2.0)
-    rake (11.3.0)
+    rake (12.0.0)
     responders (2.3.0)
       railties (>= 4.2.0, < 5.1)
     rspec-core (3.5.4)
@@ -167,10 +165,10 @@ GEM
     sqlite3 (1.3.12)
     term-ansicolor (1.4.0)
       tins (~> 1.0)
-    thor (0.19.1)
+    thor (0.19.4)
     thread_safe (0.3.5)
     timecop (0.8.1)
-    tins (1.12.0)
+    tins (1.13.0)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
     uniform_notifier (1.10.0)
@@ -192,7 +190,7 @@ DEPENDENCIES
   bullet
   coveralls
   devise (~> 4.2.0)
-  factory_girl_rails (~> 4.7.0)
+  factory_girl_rails (~> 4.8.0)
   rails (~> 5.0.0)
   rails-controller-testing
   rspec-rails (~> 3.5.1)

data/README.md

@@ -22,13 +22,17 @@
 * Grouping notifications (grouping like `"Kevin and 7 other users posted comments to this article"`)
 * Email notification
 * Batch email notification
+* Subscription management
 * Integration with [Devise](https://github.com/plataformatec/devise) authentication
 
 ### Notification index
 <kbd>![notification-index](https://raw.githubusercontent.com/simukappu/activity_notification/images/activity_notification_index.png)</kbd>
 
 ### Plugin notifications
-<kbd>![plugin-notifications](https://raw.githubusercontent.com/simukappu/activity_notification/images/activity_notification_plugin_focus.png)</kbd>
+<kbd>![plugin-notifications](https://raw.githubusercontent.com/simukappu/activity_notification/images/activity_notification_plugin_focus_with_subscription.png)</kbd>
+
+### Subscription management
+<kbd>![subscription-management](https://raw.githubusercontent.com/simukappu/activity_notification/images/activity_notification_subscription_management.png)</kbd>
 
 `activity_notification` deeply uses [PublicActivity](https://github.com/pokonski/public_activity) as reference in presentation layer.
 
@@ -57,11 +61,15 @@
     2. [Email templates](#email-templates)
     3. [i18n for email](#i18n-for-email)
   2. [Batch email notification](#batch-email-notification)
-    1. [Setup mailer](#setup-mailer)
+    1. [Setup batch mailer](#setup-batch-mailer)
     2. [Batch email templates](#batch-email-templates)
     3. [i18n for batch email](#i18n-for-batch-email)
   3. [Grouping notifications](#grouping-notifications)
-  4. [Integration with Devise](#integration-with-devise)
+  4. [Subscription management](#subscription-management)
+    1. [Setup subscriptions](#setup-subscriptions)
+    2. [Manage subscriptions](#manage-subscriptions)
+    3. [Customize Subscriptions](#customize-subscriptions)
+  5. [Integration with Devise](#integration-with-devise)
 4. [Testing](#testing)
 5. [Documentation](#documentation)
 6. **[Common examples](#common-examples)**
@@ -85,7 +93,7 @@ gem 'activity_notification'
 After you install `activity_notification` and add it to your Gemfile, you need to run the generator:
 
 ```console
-$ rails generate activity_notification:install
+$ bin/rails generate activity_notification:install
 ```
 
 The generator will install an initializer which describes all configuration options of `activity_notification`.
@@ -97,8 +105,8 @@ Currently `activity_notification` is only supported with ActiveRecord.
 Create migration for notifications and migrate the database in your Rails project:
 
 ```console
-$ rails generate activity_notification:migration
-$ rake db:migrate
+$ bin/rails generate activity_notification:migration
+$ bin/rake db:migrate
 ```
 
 ### Configuring models
@@ -124,7 +132,7 @@ end
 
 Configure your notifiable model (e.g. app/models/comment.rb).
 Add `acts_as_notifiable` configuration to your notifiable model representing activity to notify.
-You have to define notification targets for all notifications from this notifiable model by `:targets` option. Other configurations are options. `:notifiable_path` option is a path to move when the notification will be opened by the target user.
+You have to define notification targets for all notifications from this notifiable model by `:targets` option. Other configurations are options. `:notifiable_path` option is a path to move when the notification is opened by the target user.
 
 ```ruby
 class Article < ActiveRecord::Base
@@ -145,8 +153,8 @@ class Comment < ActiveRecord::Base
     targets: ->(comment, key) {
       ([comment.article.user] + comment.article.commented_users.to_a - [comment.user]).uniq
     },
-    # Path to move when the notification will be opened by the target user
-    # This is a optional since activity_notification uses polymorphic_path as default
+    # Path to move when the notification is opened by the target user
+    # This is an optional configuration since activity_notification uses polymorphic_path as default
     notifiable_path: :article_notifiable_path
 
   def article_notifiable_path
@@ -160,20 +168,20 @@ end
 `activity_notification` provides view templates to customize your notification views. The view generator can generate default views for all targets.
 
 ```console
-$ rails generate activity_notification:views
+$ bin/rails generate activity_notification:views
 ```
 
 If you have multiple target models in your application, such as `User` and `Admin`, you will be able to have views based on the target like `notifications/users/index` and `notifications/admins/index`. If no view is found for the target, `activity_notification` will use the default view at `notifications/default/index`. You can also use the generator to generate views for the specified target:
 
 ```console
-$ rails generate activity_notification:views users
+$ bin/rails generate activity_notification:views users
 ```
 
 If you would like to generate only a few sets of views, like the ones for the `notifications` (for notification views) and `mailer` (for notification email views),
 you can pass a list of modules to the generator with the `-v` flag.
 
 ```console
-$ rails generate activity_notification:views -v notifications
+$ bin/rails generate activity_notification:views -v notifications
 ```
 
 ### Configuring controllers
@@ -183,7 +191,7 @@ If the customization at the views level is not enough, you can customize each co
 1. Create your custom controllers using the generator with a target:
 
     ```console
-    $ rails generate activity_notification:controllers users
+    $ bin/rails generate activity_notification:controllers users
     ```
 
     If you specify `users` as the target, controllers will be created in `app/controllers/users/`.
@@ -191,14 +199,14 @@ If the customization at the views level is not enough, you can customize each co
 
     ```ruby
     class Users::NotificationsController < ActivityNotification::NotificationsController
-      # GET /:target_type/:target_id/notifcations
+      # GET /:target_type/:target_id/notifications
       # def index
       #   super
       # end
 
       # ...
 
-      # POST /:target_type/:target_id/notifcations/:id/open
+      # POST /:target_type/:target_id/notifications/:id/open
       # def open
       #   super
       # end
@@ -210,19 +218,17 @@ If the customization at the views level is not enough, you can customize each co
 2. Tell the router to use this controller:
 
     ```ruby
-    notify_to :users, controllers: { notifcations: 'users/notifcations' }
+    notify_to :users, controller: 'users/notifications'
     ```
 
-3. Generate views from `activity_notification/notifcations/users` to `users/notifcations/users`. Since the controller was changed, it won't use the default views located in `activity_notification/notifcations/default`.
-
-4. Finally, change or extend the desired controller actions.
+3. Finally, change or extend the desired controller actions.
 
     You can completely override a controller action
     ```ruby
     class Users::NotificationsController < ActivityNotification::NotificationsController
       # ...
 
-      # POST /:target_type/:target_id/notifcations/:id/open
+      # POST /:target_type/:target_id/notifications/:id/open
       def open
         # Custom code to open notification here
 
@@ -341,7 +347,7 @@ If you would like to fallback to a partial, you can utilize the `:fallback` para
 <%= render_notification(@notification, target: :users, fallback: :default) %>
 ```
 
-When used in this manner, if a partial with the specified `:key` cannot be located it will use the partial defined in the `:fallback` instead. In the example above this would resolve to `activity_notification/notifications/users/_default.html.(|erb|haml|slim|something_else)`.
+When used in this manner, if a partial with the specified `:key` cannot be located, it will use the partial defined in the `:fallback` instead. In the example above this would resolve to `activity_notification/notifications/users/_default.html.(|erb|haml|slim|something_else)`.
 
 If you do not specify `:target` option like this,
 
@@ -419,7 +425,7 @@ You can also configure them for each model by acts_as roles like these.
 class User < ActiveRecord::Base
   # Example using confirmed_at of devise field
   # to decide whether activity_notification sends notification email to this user
-  acts_as_notification_target email: :email, email_allowed: :confirmed_at
+  acts_as_target email: :email, email_allowed: :confirmed_at
 end
 ```
 
@@ -465,7 +471,7 @@ notification:
 
 `activity_notification` provides batch email notification to the notification targets. You can send notification email daily, hourly or weekly and so on with a scheduler like `whenever`.
 
-#### Setup mailer
+#### Setup batch mailer
 
 First, you need to set up the default URL options for the `activity_notification` mailer in each environment.
 
@@ -476,17 +482,17 @@ config.email_enabled = true
 config.mailer_sender = 'your_notification_sender@example.com'
 ```
 
-You can also configure them for each target model by `acts_as_notification_target` role like this.
+You can also configure them for each target model by `acts_as_target` role like this.
 
 ```ruby
 class User < ActiveRecord::Base
   # Example using confirmed_at of devise field
   # to decide whether activity_notification sends batch notification email to this user
-  acts_as_notification_target email: :email, batch_email_allowed: :confirmed_at
+  acts_as_target email: :email, batch_email_allowed: :confirmed_at
 end
 ```
 
-Then, you can automatically send batch notification email for unopened notifications only to the all specified targets with `batch_key`.
+Then, you can send batch notification email for unopened notifications only to the all specified targets with `batch_key`.
 
 ```ruby
 # Send batch notification email to the users with unopened notifications
@@ -503,7 +509,7 @@ User.send_batch_unopened_notification_email(batch_key: 'batch.comment.post', fil
 #### Batch email templates
 
 `activity_notification` will look for batch email template in the same way as email notification using `batch_key`.
-`batch_key` is specified by `:batch_key` option. If the option is not specified, The key of the first notification will be used as `batch_key`.
+`batch_key` is specified by `:batch_key` option. If this option is not specified, the key of the first notification will be used as `batch_key`.
 
 #### i18n for batch email
 
@@ -570,6 +576,127 @@ notification:
 
 Then, you will see `Kevin and 7 other users replied 10 comments to your article"`.
 
+
+### Subscription management
+
+`activity_notification` provides the function for subscription management of notifications and notification email.
+
+#### Setup subscriptions
+
+Subscription management is disabled as default. You can configure to enable subscription management in initializer `activity_notification.rb`.
+
+```ruby
+config.subscription_enabled = true
+```
+
+This makes all target model subscribers. You can also configure them for each target model by acts_as_target role like this.
+
+```ruby
+class User < ActiveRecord::Base
+  # Example using confirmed_at of devise field
+  # to decide whether activity_notification manages subscriptions of this user
+  acts_as_target email: :email, email_allowed: :confirmed_at, subscription_allowed: confirmed_at
+end
+```
+
+If you do not have subscriptions table in you database, create migration for subscriptions and migrate the database in your Rails project:
+
+```console
+$ bin/rails generate activity_notification:migration CreateSubscriptions -t subscriptions
+$ bin/rake db:migrate
+```
+
+
+#### Manage subscriptions
+
+Subscriptions are managed by `Subscription` model record which belongs to target and key of the notification.
+`Subscription#subscribing` manages subscription of notifications.
+`true` means the target will receive the notifications with this key.
+`false` means the target will not receive these notifications.
+`Subscription#subscribing_to_email` manages subscription of notification email.
+`true` means the target will receive the notification email with this key including batch notification email with this `batch_key`.
+`false` means the target will not receive these notification email.
+
+As default, all target subscribes to notification and notification email when subscription record does not exist in your database.
+You can change this `subscribe_as_default` parameter in initializer `activity_notification.rb`.
+
+```ruby
+config.subscribe_as_default = false
+```
+
+Then, all target does not subscribe to notification and notification email and will not receive any notifications as default.
+
+You can create subscription record from subscription API in your target model like this:
+
+```ruby
+# Subscribe 'comment.reply' notifications and notification email
+user.create_subscription(key: 'comment.reply')
+
+# Subscribe 'comment.reply' notifications but does not subscribe notification email
+user.create_subscription(key: 'comment.reply', subscribing_to_email: false)
+
+# Unsubscribe 'comment.reply' notifications and notification email
+user.create_subscription(key: 'comment.reply', subscribing: false)
+```
+
+You can also update subscriptions like this:
+
+```ruby
+# Subscribe 'comment.reply' notifications and notification email
+user.find_or_create_subscription('comment.reply').subscribe
+
+# Unsubscribe 'comment.reply' notifications and notification email
+user.find_or_create_subscription('comment.reply').unsubscribe
+
+# Unsubscribe 'comment.reply' notification email
+user.find_or_create_subscription('comment.reply').unsubscribe_to_email
+```
+
+#### Customize subscriptions
+
+`activity_notification` provides basic controllers and views to manage the subscriptions.
+
+Add subscription routing to `config/routes.rb` for the target (e.g. `:users`):
+
+```ruby
+Rails.application.routes.draw do
+  subscribed_by :users
+end
+```
+
+or, you can also configure it with notifications like this:
+
+```ruby
+Rails.application.routes.draw do
+  notify_to :users, with_subscription: true
+end
+```
+
+Then, you can access `users/1/subscriptions` and use `subscriptions_controller` or `subscriptions_with_devise_controller` to manage the subscriptions.
+
+If you would like to customize subscription controllers or views, you can use generators like notifications:
+
+* Customize subscription controllers
+
+    1. Create your custom controllers using controller generator with a target:
+
+        ```console
+        $ bin/rails generate activity_notification:controllers users -c subscriptions subscriptions_with_devise
+        ```
+
+    2. Tell the router to use this controller:
+
+        ```ruby
+        notify_to :users, with_subscription: { controller: 'users/subscriptions' }
+        ```
+
+* Customize subscription views
+
+    ```console
+    $ bin/rails generate activity_notification:views users -v subscriptions
+    ```
+
+
 ### Integration with Devise
 
 `activity_notification` supports to integrate with devise authentication.