activity_notification 1.0.2 → 1.1.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (105) hide show
  1. checksums.yaml +4 -4
  2. data/.codeclimate.yml +33 -0
  3. data/.rubocop.yml +1157 -0
  4. data/.yardopts +3 -0
  5. data/CHANGELOG.md +25 -0
  6. data/Gemfile.lock +15 -17
  7. data/README.md +154 -27
  8. data/activity_notification.gemspec +1 -1
  9. data/app/controllers/activity_notification/notifications_controller.rb +30 -104
  10. data/app/controllers/activity_notification/notifications_with_devise_controller.rb +1 -33
  11. data/app/controllers/activity_notification/subscriptions_controller.rb +184 -0
  12. data/app/controllers/activity_notification/subscriptions_with_devise_controller.rb +6 -0
  13. data/app/mailers/activity_notification/mailer.rb +3 -3
  14. data/app/views/activity_notification/notifications/default/_index.html.erb +3 -0
  15. data/app/views/activity_notification/notifications/default/index.html.erb +8 -10
  16. data/app/views/activity_notification/notifications/default/show.html.erb +24 -2
  17. data/app/views/activity_notification/subscriptions/default/_form.html.erb +52 -0
  18. data/app/views/activity_notification/subscriptions/default/_notification_keys.html.erb +89 -0
  19. data/app/views/activity_notification/subscriptions/default/_subscription.html.erb +73 -0
  20. data/app/views/activity_notification/subscriptions/default/_subscriptions.html.erb +13 -0
  21. data/app/views/activity_notification/subscriptions/default/create.js.erb +5 -0
  22. data/app/views/activity_notification/subscriptions/default/destroy.js.erb +5 -0
  23. data/app/views/activity_notification/subscriptions/default/index.html.erb +197 -0
  24. data/app/views/activity_notification/subscriptions/default/show.html.erb +177 -0
  25. data/app/views/activity_notification/subscriptions/default/subscribe.js.erb +8 -0
  26. data/app/views/activity_notification/subscriptions/default/subscribe_to_email.js.erb +6 -0
  27. data/app/views/activity_notification/subscriptions/default/unsubscribe.js.erb +8 -0
  28. data/app/views/activity_notification/subscriptions/default/unsubscribe_to_email.js.erb +6 -0
  29. data/gemfiles/Gemfile.rails-4.2.lock +18 -20
  30. data/gemfiles/Gemfile.rails-5.0.lock +18 -20
  31. data/lib/activity_notification.rb +7 -3
  32. data/lib/activity_notification/apis/notification_api.rb +95 -61
  33. data/lib/activity_notification/apis/subscription_api.rb +51 -0
  34. data/lib/activity_notification/common.rb +1 -1
  35. data/lib/activity_notification/config.rb +65 -17
  36. data/lib/activity_notification/controllers/common_controller.rb +118 -0
  37. data/lib/activity_notification/controllers/devise_authentication_controller.rb +41 -0
  38. data/lib/activity_notification/helpers/view_helpers.rb +131 -3
  39. data/lib/activity_notification/mailers/helpers.rb +6 -8
  40. data/lib/activity_notification/models/concerns/notifiable.rb +45 -27
  41. data/lib/activity_notification/models/concerns/subscriber.rb +149 -0
  42. data/lib/activity_notification/models/concerns/target.rb +100 -66
  43. data/lib/activity_notification/models/notification.rb +7 -5
  44. data/lib/activity_notification/models/subscription.rb +93 -0
  45. data/lib/activity_notification/rails/routes.rb +148 -33
  46. data/lib/activity_notification/renderable.rb +3 -4
  47. data/lib/activity_notification/roles/acts_as_notifiable.rb +14 -1
  48. data/lib/activity_notification/roles/acts_as_target.rb +11 -8
  49. data/lib/activity_notification/version.rb +1 -1
  50. data/lib/generators/activity_notification/controllers_generator.rb +2 -2
  51. data/lib/generators/activity_notification/install_generator.rb +0 -1
  52. data/lib/generators/activity_notification/migration/migration_generator.rb +8 -2
  53. data/lib/generators/activity_notification/models_generator.rb +53 -0
  54. data/lib/generators/activity_notification/views_generator.rb +7 -7
  55. data/lib/generators/templates/activity_notification.rb +17 -3
  56. data/lib/generators/templates/controllers/notifications_controller.rb +18 -17
  57. data/lib/generators/templates/controllers/notifications_with_devise_controller.rb +18 -17
  58. data/lib/generators/templates/controllers/subscriptions_controller.rb +79 -0
  59. data/lib/generators/templates/controllers/subscriptions_with_devise_controller.rb +87 -0
  60. data/lib/generators/templates/migrations/migration.rb +57 -0
  61. data/lib/generators/templates/models/README +10 -0
  62. data/lib/generators/templates/{notification → models}/notification.rb +1 -3
  63. data/lib/generators/templates/models/subscription.rb +4 -0
  64. data/spec/concerns/apis/notification_api_spec.rb +48 -11
  65. data/spec/concerns/apis/subscription_api_spec.rb +167 -0
  66. data/spec/concerns/models/notifiable_spec.rb +60 -0
  67. data/spec/concerns/models/subscriber_spec.rb +525 -0
  68. data/spec/concerns/models/target_spec.rb +271 -42
  69. data/spec/controllers/common_controller_spec.rb +25 -0
  70. data/spec/controllers/dummy_common_controller.rb +5 -0
  71. data/spec/controllers/notifications_controller_shared_examples.rb +2 -6
  72. data/spec/controllers/subscriptions_controller_shared_examples.rb +735 -0
  73. data/spec/controllers/subscriptions_controller_spec.rb +12 -0
  74. data/spec/controllers/subscriptions_with_devise_controller_spec.rb +91 -0
  75. data/spec/factories/dummy/dummy_subscriber.rb +4 -0
  76. data/spec/factories/subscriptions.rb +8 -0
  77. data/spec/generators/controllers_generator_spec.rb +25 -2
  78. data/spec/generators/migration/migration_generator_spec.rb +3 -3
  79. data/spec/generators/models_generator_spec.rb +96 -0
  80. data/spec/generators/views_generator_spec.rb +84 -0
  81. data/spec/helpers/view_helpers_spec.rb +143 -0
  82. data/spec/mailers/mailer_spec.rb +5 -4
  83. data/spec/models/dummy/dummy_subscriber_spec.rb +5 -0
  84. data/spec/models/notification_spec.rb +7 -7
  85. data/spec/models/subscription_spec.rb +158 -0
  86. data/spec/rails_app/app/controllers/users/notifications_controller.rb +67 -0
  87. data/spec/rails_app/app/controllers/users/notifications_with_devise_controller.rb +75 -0
  88. data/spec/rails_app/app/controllers/users/subscriptions_controller.rb +79 -0
  89. data/spec/rails_app/app/controllers/users/subscriptions_with_devise_controller.rb +87 -0
  90. data/spec/rails_app/app/models/admin.rb +1 -0
  91. data/spec/rails_app/app/models/dummy/dummy_subscriber.rb +4 -0
  92. data/spec/rails_app/app/models/user.rb +2 -1
  93. data/spec/rails_app/app/views/activity_notification/mailer/dummy_subscribers/test_key.text.erb +1 -0
  94. data/spec/rails_app/app/views/articles/index.html.erb +6 -0
  95. data/spec/rails_app/config/initializers/activity_notification.rb +17 -3
  96. data/spec/rails_app/config/routes.rb +2 -2
  97. data/spec/rails_app/db/migrate/20160715050420_create_activity_notification_tables.rb +33 -0
  98. data/spec/rails_app/db/schema.rb +18 -0
  99. data/spec/roles/acts_as_notifiable_spec.rb +1 -1
  100. data/spec/roles/acts_as_target_spec.rb +1 -1
  101. metadata +70 -11
  102. data/lib/generators/activity_notification/notification/notification_generator.rb +0 -20
  103. data/lib/generators/templates/active_record/migration.rb +0 -18
  104. data/spec/generators/notification/notification_generator_spec.rb +0 -41
  105. data/spec/rails_app/db/migrate/20160715050420_create_notifications.rb +0 -18
data/.yardopts CHANGED
@@ -1,3 +1,6 @@
1
1
  --no-private
2
2
  --hide-api private
3
3
  --plugin activesupport-concern
4
+ --exclude /templates/
5
+ app/**/*.rb
6
+ lib/**/*.rb
data/CHANGELOG.md CHANGED
@@ -1,3 +1,23 @@
1
+ ## 1.1.0 / 2016-12-18
2
+ [Full Changelog](http://github.com/simukappu/activity_notification/compare/v1.0.2...v1.1.0)
3
+
4
+ Enhancements:
5
+
6
+ * Add subscription management framework
7
+ * Subscription management model and API
8
+ * Default subscription management controllers, routing and views
9
+ * Add Subscriber role configuration to Target role
10
+ * Add as_latest_group_member option to batch mailer API
11
+ * Add group_expiry_delay option to notification API
12
+
13
+ Bug Fixes:
14
+
15
+ * Fix unserializable error in Target#send_batch_unopened_notification_email since unnecessary options are passed to mailer
16
+
17
+ Breaking Changes:
18
+
19
+ * Remove notifiable_type from the argument of overriden method or configured lambda function for Target#batch_notification_email_allowed?
20
+
1
21
  ## 1.0.2 / 2016-11-14
2
22
  [Full Changelog](http://github.com/simukappu/activity_notification/compare/v1.0.1...v1.0.2)
3
23
 
@@ -19,6 +39,10 @@ Enhancements:
19
39
  * Add methods to get notifications for specified target type grouped by targets like `notification_index_map`
20
40
  * Arrange default notification email view templates
21
41
 
42
+ Breaking Changes:
43
+
44
+ * Use instance variables @notification.target and @notification.notifiable instead of @target and @notifiable in notification email templates
45
+
22
46
  ## 1.0.0 / 2016-10-06
23
47
  [Full Changelog](http://github.com/simukappu/activity_notification/compare/v0.0.10...v1.0.0)
24
48
 
@@ -38,6 +62,7 @@ Enhancements:
38
62
  * Make default rails version 5.0 and update gem dependency
39
63
 
40
64
  Breaking Changes:
65
+
41
66
  * Rename `opened_limit` configuration parameter to `opened_index_limit`
42
67
  * http://github.com/simukappu/activity_notification/commit/591e53cd8977220f819c11cd702503fc72dd1fd1
43
68
 
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- activity_notification (1.0.2)
4
+ activity_notification (1.1.0)
5
5
  activerecord (>= 4.2.0)
6
6
  i18n (>= 0.5.0)
7
7
  jquery-rails (>= 3.1.1)
@@ -51,19 +51,19 @@ GEM
51
51
  activesupport (>= 3.0)
52
52
  railties (>= 3.0)
53
53
  rspec-rails (>= 2.2)
54
- arel (7.1.2)
54
+ arel (7.1.4)
55
55
  bcrypt (3.1.11)
56
56
  builder (3.2.2)
57
- bullet (5.4.2)
57
+ bullet (5.4.3)
58
58
  activesupport (>= 3.0.0)
59
59
  uniform_notifier (~> 1.10.0)
60
- concurrent-ruby (1.0.2)
61
- coveralls (0.8.15)
60
+ concurrent-ruby (1.0.3)
61
+ coveralls (0.8.17)
62
62
  json (>= 1.8, < 3)
63
63
  simplecov (~> 0.12.0)
64
64
  term-ansicolor (~> 1.3)
65
65
  thor (~> 0.19.1)
66
- tins (>= 1.6.0, < 2)
66
+ tins (~> 1.6)
67
67
  devise (4.2.0)
68
68
  bcrypt (~> 3.0)
69
69
  orm_adapter (~> 0.1)
@@ -73,10 +73,10 @@ GEM
73
73
  diff-lcs (1.2.5)
74
74
  docile (1.1.5)
75
75
  erubis (2.7.0)
76
- factory_girl (4.7.0)
76
+ factory_girl (4.8.0)
77
77
  activesupport (>= 3.0.0)
78
- factory_girl_rails (4.7.0)
79
- factory_girl (~> 4.7.0)
78
+ factory_girl_rails (4.8.0)
79
+ factory_girl (~> 4.8.0)
80
80
  railties (>= 3.0.0)
81
81
  globalid (0.3.7)
82
82
  activesupport (>= 4.1.0)
@@ -95,13 +95,11 @@ GEM
95
95
  mime-types-data (~> 3.2015)
96
96
  mime-types-data (3.2016.0521)
97
97
  mini_portile2 (2.1.0)
98
- minitest (5.9.1)
98
+ minitest (5.10.1)
99
99
  nio4r (1.2.1)
100
- nokogiri (1.6.8)
100
+ nokogiri (1.6.8.1)
101
101
  mini_portile2 (~> 2.1.0)
102
- pkg-config (~> 1.1.7)
103
102
  orm_adapter (0.5.0)
104
- pkg-config (1.1.7)
105
103
  rack (2.0.1)
106
104
  rack-test (0.6.3)
107
105
  rack (>= 1.0)
@@ -132,7 +130,7 @@ GEM
132
130
  method_source
133
131
  rake (>= 0.8.7)
134
132
  thor (>= 0.18.1, < 2.0)
135
- rake (11.3.0)
133
+ rake (12.0.0)
136
134
  responders (2.3.0)
137
135
  railties (>= 4.2.0, < 5.1)
138
136
  rspec-core (3.5.4)
@@ -167,10 +165,10 @@ GEM
167
165
  sqlite3 (1.3.12)
168
166
  term-ansicolor (1.4.0)
169
167
  tins (~> 1.0)
170
- thor (0.19.1)
168
+ thor (0.19.4)
171
169
  thread_safe (0.3.5)
172
170
  timecop (0.8.1)
173
- tins (1.12.0)
171
+ tins (1.13.0)
174
172
  tzinfo (1.2.2)
175
173
  thread_safe (~> 0.1)
176
174
  uniform_notifier (1.10.0)
@@ -192,7 +190,7 @@ DEPENDENCIES
192
190
  bullet
193
191
  coveralls
194
192
  devise (~> 4.2.0)
195
- factory_girl_rails (~> 4.7.0)
193
+ factory_girl_rails (~> 4.8.0)
196
194
  rails (~> 5.0.0)
197
195
  rails-controller-testing
198
196
  rspec-rails (~> 3.5.1)
data/README.md CHANGED
@@ -22,13 +22,17 @@
22
22
  * Grouping notifications (grouping like `"Kevin and 7 other users posted comments to this article"`)
23
23
  * Email notification
24
24
  * Batch email notification
25
+ * Subscription management
25
26
  * Integration with [Devise](https://github.com/plataformatec/devise) authentication
26
27
 
27
28
  ### Notification index
28
29
  <kbd>![notification-index](https://raw.githubusercontent.com/simukappu/activity_notification/images/activity_notification_index.png)</kbd>
29
30
 
30
31
  ### Plugin notifications
31
- <kbd>![plugin-notifications](https://raw.githubusercontent.com/simukappu/activity_notification/images/activity_notification_plugin_focus.png)</kbd>
32
+ <kbd>![plugin-notifications](https://raw.githubusercontent.com/simukappu/activity_notification/images/activity_notification_plugin_focus_with_subscription.png)</kbd>
33
+
34
+ ### Subscription management
35
+ <kbd>![subscription-management](https://raw.githubusercontent.com/simukappu/activity_notification/images/activity_notification_subscription_management.png)</kbd>
32
36
 
33
37
  `activity_notification` deeply uses [PublicActivity](https://github.com/pokonski/public_activity) as reference in presentation layer.
34
38
 
@@ -57,11 +61,15 @@
57
61
  2. [Email templates](#email-templates)
58
62
  3. [i18n for email](#i18n-for-email)
59
63
  2. [Batch email notification](#batch-email-notification)
60
- 1. [Setup mailer](#setup-mailer)
64
+ 1. [Setup batch mailer](#setup-batch-mailer)
61
65
  2. [Batch email templates](#batch-email-templates)
62
66
  3. [i18n for batch email](#i18n-for-batch-email)
63
67
  3. [Grouping notifications](#grouping-notifications)
64
- 4. [Integration with Devise](#integration-with-devise)
68
+ 4. [Subscription management](#subscription-management)
69
+ 1. [Setup subscriptions](#setup-subscriptions)
70
+ 2. [Manage subscriptions](#manage-subscriptions)
71
+ 3. [Customize Subscriptions](#customize-subscriptions)
72
+ 5. [Integration with Devise](#integration-with-devise)
65
73
  4. [Testing](#testing)
66
74
  5. [Documentation](#documentation)
67
75
  6. **[Common examples](#common-examples)**
@@ -85,7 +93,7 @@ gem 'activity_notification'
85
93
  After you install `activity_notification` and add it to your Gemfile, you need to run the generator:
86
94
 
87
95
  ```console
88
- $ rails generate activity_notification:install
96
+ $ bin/rails generate activity_notification:install
89
97
  ```
90
98
 
91
99
  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.
97
105
  Create migration for notifications and migrate the database in your Rails project:
98
106
 
99
107
  ```console
100
- $ rails generate activity_notification:migration
101
- $ rake db:migrate
108
+ $ bin/rails generate activity_notification:migration
109
+ $ bin/rake db:migrate
102
110
  ```
103
111
 
104
112
  ### Configuring models
@@ -124,7 +132,7 @@ end
124
132
 
125
133
  Configure your notifiable model (e.g. app/models/comment.rb).
126
134
  Add `acts_as_notifiable` configuration to your notifiable model representing activity to notify.
127
- 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.
135
+ 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.
128
136
 
129
137
  ```ruby
130
138
  class Article < ActiveRecord::Base
@@ -145,8 +153,8 @@ class Comment < ActiveRecord::Base
145
153
  targets: ->(comment, key) {
146
154
  ([comment.article.user] + comment.article.commented_users.to_a - [comment.user]).uniq
147
155
  },
148
- # Path to move when the notification will be opened by the target user
149
- # This is a optional since activity_notification uses polymorphic_path as default
156
+ # Path to move when the notification is opened by the target user
157
+ # This is an optional configuration since activity_notification uses polymorphic_path as default
150
158
  notifiable_path: :article_notifiable_path
151
159
 
152
160
  def article_notifiable_path
@@ -160,20 +168,20 @@ end
160
168
  `activity_notification` provides view templates to customize your notification views. The view generator can generate default views for all targets.
161
169
 
162
170
  ```console
163
- $ rails generate activity_notification:views
171
+ $ bin/rails generate activity_notification:views
164
172
  ```
165
173
 
166
174
  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:
167
175
 
168
176
  ```console
169
- $ rails generate activity_notification:views users
177
+ $ bin/rails generate activity_notification:views users
170
178
  ```
171
179
 
172
180
  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),
173
181
  you can pass a list of modules to the generator with the `-v` flag.
174
182
 
175
183
  ```console
176
- $ rails generate activity_notification:views -v notifications
184
+ $ bin/rails generate activity_notification:views -v notifications
177
185
  ```
178
186
 
179
187
  ### Configuring controllers
@@ -183,7 +191,7 @@ If the customization at the views level is not enough, you can customize each co
183
191
  1. Create your custom controllers using the generator with a target:
184
192
 
185
193
  ```console
186
- $ rails generate activity_notification:controllers users
194
+ $ bin/rails generate activity_notification:controllers users
187
195
  ```
188
196
 
189
197
  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
191
199
 
192
200
  ```ruby
193
201
  class Users::NotificationsController < ActivityNotification::NotificationsController
194
- # GET /:target_type/:target_id/notifcations
202
+ # GET /:target_type/:target_id/notifications
195
203
  # def index
196
204
  # super
197
205
  # end
198
206
 
199
207
  # ...
200
208
 
201
- # POST /:target_type/:target_id/notifcations/:id/open
209
+ # POST /:target_type/:target_id/notifications/:id/open
202
210
  # def open
203
211
  # super
204
212
  # end
@@ -210,19 +218,17 @@ If the customization at the views level is not enough, you can customize each co
210
218
  2. Tell the router to use this controller:
211
219
 
212
220
  ```ruby
213
- notify_to :users, controllers: { notifcations: 'users/notifcations' }
221
+ notify_to :users, controller: 'users/notifications'
214
222
  ```
215
223
 
216
- 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`.
217
-
218
- 4. Finally, change or extend the desired controller actions.
224
+ 3. Finally, change or extend the desired controller actions.
219
225
 
220
226
  You can completely override a controller action
221
227
  ```ruby
222
228
  class Users::NotificationsController < ActivityNotification::NotificationsController
223
229
  # ...
224
230
 
225
- # POST /:target_type/:target_id/notifcations/:id/open
231
+ # POST /:target_type/:target_id/notifications/:id/open
226
232
  def open
227
233
  # Custom code to open notification here
228
234
 
@@ -341,7 +347,7 @@ If you would like to fallback to a partial, you can utilize the `:fallback` para
341
347
  <%= render_notification(@notification, target: :users, fallback: :default) %>
342
348
  ```
343
349
 
344
- 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)`.
350
+ 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)`.
345
351
 
346
352
  If you do not specify `:target` option like this,
347
353
 
@@ -419,7 +425,7 @@ You can also configure them for each model by acts_as roles like these.
419
425
  class User < ActiveRecord::Base
420
426
  # Example using confirmed_at of devise field
421
427
  # to decide whether activity_notification sends notification email to this user
422
- acts_as_notification_target email: :email, email_allowed: :confirmed_at
428
+ acts_as_target email: :email, email_allowed: :confirmed_at
423
429
  end
424
430
  ```
425
431
 
@@ -465,7 +471,7 @@ notification:
465
471
 
466
472
  `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`.
467
473
 
468
- #### Setup mailer
474
+ #### Setup batch mailer
469
475
 
470
476
  First, you need to set up the default URL options for the `activity_notification` mailer in each environment.
471
477
 
@@ -476,17 +482,17 @@ config.email_enabled = true
476
482
  config.mailer_sender = 'your_notification_sender@example.com'
477
483
  ```
478
484
 
479
- You can also configure them for each target model by `acts_as_notification_target` role like this.
485
+ You can also configure them for each target model by `acts_as_target` role like this.
480
486
 
481
487
  ```ruby
482
488
  class User < ActiveRecord::Base
483
489
  # Example using confirmed_at of devise field
484
490
  # to decide whether activity_notification sends batch notification email to this user
485
- acts_as_notification_target email: :email, batch_email_allowed: :confirmed_at
491
+ acts_as_target email: :email, batch_email_allowed: :confirmed_at
486
492
  end
487
493
  ```
488
494
 
489
- Then, you can automatically send batch notification email for unopened notifications only to the all specified targets with `batch_key`.
495
+ Then, you can send batch notification email for unopened notifications only to the all specified targets with `batch_key`.
490
496
 
491
497
  ```ruby
492
498
  # 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
503
509
  #### Batch email templates
504
510
 
505
511
  `activity_notification` will look for batch email template in the same way as email notification using `batch_key`.
506
- `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`.
512
+ `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`.
507
513
 
508
514
  #### i18n for batch email
509
515
 
@@ -570,6 +576,127 @@ notification:
570
576
 
571
577
  Then, you will see `Kevin and 7 other users replied 10 comments to your article"`.
572
578
 
579
+
580
+ ### Subscription management
581
+
582
+ `activity_notification` provides the function for subscription management of notifications and notification email.
583
+
584
+ #### Setup subscriptions
585
+
586
+ Subscription management is disabled as default. You can configure to enable subscription management in initializer `activity_notification.rb`.
587
+
588
+ ```ruby
589
+ config.subscription_enabled = true
590
+ ```
591
+
592
+ This makes all target model subscribers. You can also configure them for each target model by acts_as_target role like this.
593
+
594
+ ```ruby
595
+ class User < ActiveRecord::Base
596
+ # Example using confirmed_at of devise field
597
+ # to decide whether activity_notification manages subscriptions of this user
598
+ acts_as_target email: :email, email_allowed: :confirmed_at, subscription_allowed: confirmed_at
599
+ end
600
+ ```
601
+
602
+ If you do not have subscriptions table in you database, create migration for subscriptions and migrate the database in your Rails project:
603
+
604
+ ```console
605
+ $ bin/rails generate activity_notification:migration CreateSubscriptions -t subscriptions
606
+ $ bin/rake db:migrate
607
+ ```
608
+
609
+
610
+ #### Manage subscriptions
611
+
612
+ Subscriptions are managed by `Subscription` model record which belongs to target and key of the notification.
613
+ `Subscription#subscribing` manages subscription of notifications.
614
+ `true` means the target will receive the notifications with this key.
615
+ `false` means the target will not receive these notifications.
616
+ `Subscription#subscribing_to_email` manages subscription of notification email.
617
+ `true` means the target will receive the notification email with this key including batch notification email with this `batch_key`.
618
+ `false` means the target will not receive these notification email.
619
+
620
+ As default, all target subscribes to notification and notification email when subscription record does not exist in your database.
621
+ You can change this `subscribe_as_default` parameter in initializer `activity_notification.rb`.
622
+
623
+ ```ruby
624
+ config.subscribe_as_default = false
625
+ ```
626
+
627
+ Then, all target does not subscribe to notification and notification email and will not receive any notifications as default.
628
+
629
+ You can create subscription record from subscription API in your target model like this:
630
+
631
+ ```ruby
632
+ # Subscribe 'comment.reply' notifications and notification email
633
+ user.create_subscription(key: 'comment.reply')
634
+
635
+ # Subscribe 'comment.reply' notifications but does not subscribe notification email
636
+ user.create_subscription(key: 'comment.reply', subscribing_to_email: false)
637
+
638
+ # Unsubscribe 'comment.reply' notifications and notification email
639
+ user.create_subscription(key: 'comment.reply', subscribing: false)
640
+ ```
641
+
642
+ You can also update subscriptions like this:
643
+
644
+ ```ruby
645
+ # Subscribe 'comment.reply' notifications and notification email
646
+ user.find_or_create_subscription('comment.reply').subscribe
647
+
648
+ # Unsubscribe 'comment.reply' notifications and notification email
649
+ user.find_or_create_subscription('comment.reply').unsubscribe
650
+
651
+ # Unsubscribe 'comment.reply' notification email
652
+ user.find_or_create_subscription('comment.reply').unsubscribe_to_email
653
+ ```
654
+
655
+ #### Customize subscriptions
656
+
657
+ `activity_notification` provides basic controllers and views to manage the subscriptions.
658
+
659
+ Add subscription routing to `config/routes.rb` for the target (e.g. `:users`):
660
+
661
+ ```ruby
662
+ Rails.application.routes.draw do
663
+ subscribed_by :users
664
+ end
665
+ ```
666
+
667
+ or, you can also configure it with notifications like this:
668
+
669
+ ```ruby
670
+ Rails.application.routes.draw do
671
+ notify_to :users, with_subscription: true
672
+ end
673
+ ```
674
+
675
+ Then, you can access `users/1/subscriptions` and use `subscriptions_controller` or `subscriptions_with_devise_controller` to manage the subscriptions.
676
+
677
+ If you would like to customize subscription controllers or views, you can use generators like notifications:
678
+
679
+ * Customize subscription controllers
680
+
681
+ 1. Create your custom controllers using controller generator with a target:
682
+
683
+ ```console
684
+ $ bin/rails generate activity_notification:controllers users -c subscriptions subscriptions_with_devise
685
+ ```
686
+
687
+ 2. Tell the router to use this controller:
688
+
689
+ ```ruby
690
+ notify_to :users, with_subscription: { controller: 'users/subscriptions' }
691
+ ```
692
+
693
+ * Customize subscription views
694
+
695
+ ```console
696
+ $ bin/rails generate activity_notification:views users -v subscriptions
697
+ ```
698
+
699
+
573
700
  ### Integration with Devise
574
701
 
575
702
  `activity_notification` supports to integrate with devise authentication.