notification-settings 1.2.6 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4193e47d53d1953047f50b4e5d47cced6258e9bfb55a95f65e8bf387025cce93
-  data.tar.gz: 967ff77853953c85928e67b1ba76091c8ddd97111f7207ed5c53271dfe1b594f
+  metadata.gz: 1be12c7320f2f51d85d54709ccec7f39fd32e9ec3f678c0635f845b47a282a77
+  data.tar.gz: dc137bbc872c9a9316c1b0f89a2fc227cb12e05d259f1fa5382fdd11d8598cd2
 SHA512:
-  metadata.gz: 7e744b92cb72fc7b3bc1c4e3b278a9e31c0a3cd915986cd913b7adcf49db1809e70569ef88c9719dfeed66ffeaf527ad5fe0517acaf3190f31bdcc0556ca9af9
-  data.tar.gz: 163007c12e9559d559defa7fe71982c58fc6a2f7b46887843cbe7fd06f3e0375e1ffda7e062c3adcf6f7b8b397b5607afccb7dfbaa7219b7644e159623acf326
+  metadata.gz: efa0e738bc0e76b48f27698665a37fcebed7bb771719673ccca50a23668824a3626ad75436f141db27d781d4e9205f7c1a6dfbc4e3d6812bb848eed8612b1d2d
+  data.tar.gz: 79303e8bc9c434431e57b3cf6992b6f856108e72552503251b46b9b205c4bfdc16cf4efcc6e7cf69c7a242eb3425eea436df0cd8fb6a85defa05b0faa4377295

data/README.md

@@ -1,6 +1,6 @@
 # NotificationSettings
 
-[![Gem Version](https://badge.fury.io/rb/notification-settings.svg)](https://badge.fury.io/rb/notification-settings) <img src="https://travis-ci.org/jonhue/notifications-rails.svg?branch=master" />
+[![Gem Version](https://badge.fury.io/rb/notification-settings.svg)](https://badge.fury.io/rb/notification-settings) ![Travis](https://travis-ci.com/jonhue/notifications-rails.svg?branch=master)
 
 Integrates with your authentication solution to craft a personalized user notification platform.
 
@@ -10,20 +10,18 @@ Integrates with your authentication solution to craft a personalized user notifi
 
 * [Installation](#installation)
 * [Usage](#usage)
-    * [Categories](#categories)
-    * [Settings](#settings)
-        * [Category specific settings](#category-specific-settings)
-        * [Pusher specific settings](#pusher-specific-settings)
-        * [Updating settings](#updating-settings)
-    * [Subscriptions](#subscriptions)
-    * [Status](#status)
+  * [Categories](#categories)
+  * [Settings](#settings)
+    * [Category-specific settings](#category-specific-settings)
+    * [Pusher-specific settings](#pusher-specific-settings)
+    * [Updating settings](#updating-settings)
+  * [Subscriptions](#subscriptions)
+  * [Status](#status)
 * [Configuration](#configuration)
-    * [Status](#status)
+  * [Status](#status)
 * [To Do](#to-do)
 * [Contributing](#contributing)
-    * [Contributors](#contributors)
-    * [Semantic versioning](#semantic-versioning)
-* [License](#license)
+  * [Semantic versioning](#semantic-versioning)
 
 ---
 
@@ -43,14 +41,9 @@ Or install it yourself as:
 
     $ gem install notification-settings
 
-If you always want to be up to date fetch the latest from GitHub in your `Gemfile`:
-
-```ruby
-gem 'notification-settings', github: 'jonhue/notifications-rails'
-```
-
 Now run the generator:
 
+    $ rails g notification_handler:install
     $ rails g notification_settings:install
 
 To wrap things up, migrate the changes to your database:
@@ -61,10 +54,22 @@ To wrap things up, migrate the changes to your database:
 
 ## Usage
 
-NotificationSettings will create a `NotificationSettings::Setting` record for every newly created `notification_target`-object. It is accessible by calling:
+First, you have to add some attributes to every model that acts as a `notification_target`:
 
 ```ruby
-User.first.notification_setting
+class User
+  # ...
+
+  notification_target
+end
+```
+
+```ruby
+# A Hashie::Mash object that stores all the settings of a notification target.
+add_column :users, :settings, :text
+
+# A string that describes a notification-relevant state of a notification target.
+add_column :users, :status, :string
 ```
 
 ### Categories
@@ -72,7 +77,7 @@ User.first.notification_setting
 NotificationSettings uses categories to allow your notification targets to define specific preferences. This is how you are able to specify the `category` of a `Notification` record:
 
 ```ruby
-notification = Notification.create target: User.first, object: Recipe.first, category: 'notification'
+notification = Notification.create(target: User.first, object: Recipe.first, category: :notification)
 ```
 
 **Note:** The `category` attribute of any new `Notification` record will default to the [`default_category` configuration](#configuration).
@@ -89,35 +94,82 @@ Notification.follow_category
 
 ### Settings
 
-You can disable notifications for a given notification target:
+You can completely disable notifications for a given notification target:
 
 ```ruby
-s = User.first.notification_setting
-s.settings[:enabled] = false
+settings = User.first.settings
+
+settings.enabled = false
 ```
 
 This will prevent you from creating any new notifications with this user as target.
 
-#### Category specific settings
+The default is `true` (enabled) for this setting and the other settings.
+
+#### Category-specific settings
+
+A user can also have category-specific settings:
 
-A user can also have category specific settings:
+```ruby
+settings.categories!.send("#{category}!").enabled = false
+```
+
+#### Delivery-method-specific settings
+
+He can have global or category-specific delivery method settings:
 
 ```ruby
-s.category_settings[:category] = { enabled: false }
+settings.delivery_methods!.enabled = false                              # Prevent delivering via *any* delivery method
+settings.delivery_methods!.email!.enabled = false                       # Prevent delivering via the :email delivery method
+settings.categories!.category!.delivery_methods!.email!.enabled = false # Prevent delivering via the :email delivery method for :category
 ```
 
-#### Pusher specific settings
+#### Form objects
 
-He can have global or category specific pusher settings:
+NotificationSettings comes with three form objects that simplify building forms for updating settings.
+
+##### PreferencesForm
+
+The preferences form has just one attribute: `enabled`. It can be used to update the global notification setting.
 
 ```ruby
-s.settings[:ActionMailer] = false
-s.category_settings[:category] = { ActionMailer: false }
+user = User.first
+
+form = NotificationSettings::PreferencesForm.new(enabled: user.settings.enabled)
+form.valid?
+
+user.settings.enabled = form.enabled
 ```
 
-#### Updating settings
+##### CategoryPreferencesForm
+
+The category preferences form has one attribute per category. It can be used to update category-specific settings.
+
+```ruby
+user = User.first
 
-...
+form = NotificationSettings::CategoryPreferencesForm.new(user.settings.categories_.to_h)
+form.valid?
+
+form.changed_attributes.each do |category|
+  user.settings.categories!.send(category, form.send(category))
+end
+```
+
+##### DeliveryMethodPreferencesForm
+
+The delivery method preferences form has one attribute per category and a general `enabled` attribute. It can be used to update delivery-method-specific settings or to disable all delivery methods.
+
+```ruby
+user = User.first
+
+form = NotificationSettings::DeliveryMethodPreferencesForm.new(user.settings.delivery_methods_.to_h)
+form.valid?
+
+form.changed_attributes.each do |delivery_method|
+  user.settings.delivery_methods!.send(delivery_method, form.send(delivery_method))
+end
+```
 
 ### Subscriptions
 
@@ -126,14 +178,14 @@ Subscriptions are a way to better handle settings for notifications from differe
 This is how to subscribe/unsubscribe a target to an object:
 
 ```ruby
-User.first.subscribe Recipe.first
-User.first.unsubscribe Recipe.first
+User.first.subscribe(Recipe.first)
+User.first.unsubscribe(Recipe.first)
 ```
 
 Now you can easily notify all subscribers from the subscribable object:
 
 ```ruby
-Recipe.first.notify_subscribers push: :ActionMailer
+Recipe.first.notify_subscribers(delivery_method: :ActionMailer)
 ```
 
 Let's assume that we have a group which has multiple chats. When sending notifications to subscribers of a given chat, we only want them to get notified. But when sending notifications about the group, we want to have everyone notified, that is either subscribed to the group or subscribed to one of its chats. To do that you have to add the `private` method `notification_dependents` to your model (in this case `Group`) and return an array of ActiveRecord objects whose subscribers should receive notifications for objects of this class.
@@ -145,7 +197,7 @@ has_many :talks
 private
 
 def notification_dependents
-    self.chats
+  self.chats
 end
 ```
 
@@ -153,21 +205,41 @@ It is possible to override that behavior when notifying subscribers:
 
 ```ruby
 # Disable notification dependents
-Group.first.notify_subscribers dependents: nil
+Group.first.notify_subscribers(dependents: nil)
 
 # Override notification dependents
-Group.first.notify_subscribers dependents: Group.first.chats + Group.first.talks
+Group.first.notify_subscribers(dependents: Group.first.chats + Group.first.talks)
 ```
 
-You can customize settings for a single subscription just as you would for a notification target:
+You can customize settings & status for a single subscription just as you would for a notification target:
 
 ```ruby
-s = User.first.notification_subscriptions.first.notification_setting
-s.settings[:enabled] = false
+user = User.first
+subscription = user.notification_subscriptions.first
+
+subscription.settings.enabled = false
+subscription.status = 'online'
+subscription.save
 ```
 
 [Learn more](#settings)
 
+You can add associations to your subscriber/subscribable classes if you need easy access to all their subscriptions:
+
+```ruby
+# For subscribers:
+# List all subscriptions of a subscriber
+subscriber.notification_subscribables
+# List all subscribables of a specific type a subscriber subscribed to
+has_many :subscribed_products, through: :notification_subscribables, source: :subscribable, source_type: 'Product'
+
+# For subscribables:
+# List all subscriptions of a subscriber
+subscribable.notification_subscribers
+# List all subscribers of a specific type that subscribed to a subscribable
+has_many :subscribed_users, through: :notification_subscribers, source: :subscriber, source_type: 'User'
+```
+
 ### Status
 
 NotificationSettings comes with a handy feature called Status. The status of a record can temporarily disable the ability to create notifications for or to push notifications of a target.
@@ -175,8 +247,7 @@ NotificationSettings comes with a handy feature called Status. The status of a r
 This is how to define a status:
 
 ```ruby
-User.first.notification_setting.status = 'do not disturb'
-User.first.notification_setting.save
+User.first.update(status: 'do not disturb')
 ```
 
 **Note:** You can set `status` to any string you like.
@@ -185,12 +256,12 @@ User.first.notification_setting.save
 
 If you have set `status` to a custom value, you can get back to using the defaults by setting it back to `nil`.
 
-You can define statuses that prevent creating new notifications for a target and statuses that just prevent pushing them:
+You can define statuses that prevent creating new notifications for a target and statuses that just prevent delivering them:
 
 ```ruby
 NotificationSettings.configure do |config|
-    config.do_not_notify_statuses = ['do not notify']
-    config.do_not_push_statuses = ['do not disturb']
+  config.do_not_notify_statuses  = ['do not notify']
+  config.do_not_deliver_statuses = ['do not disturb']
 end
 ```
 
@@ -202,11 +273,13 @@ You can configure NotificationSettings by passing a block to `configure`. This c
 
 ```ruby
 NotificationSettings.configure do |config|
-    config.default_category = 'notification'
+  config.categories = [:notification]
 end
 ```
 
-**`default_category`** Choose your default notification category. Takes a string. Defaults to `'notification'`.
+**`categories`** Choose your default notification category. Takes an array of symbols. Defaults to `[:notification]`.
+
+**`default_category`** Choose your default notification category. Takes a symbol. Defaults to `:notification`.
 
 ### Status
 
@@ -214,17 +287,19 @@ end
 
 **`offline_after`** Time duration without activity after which the status defaults to `'offline'`. Takes a time. Defaults to `3.hours`.
 
-**`last_seen`** Stringified datetime attribute name of `object` that defines the time of the last activity. Takes a string. Defaults to `'last_seen'`.
+**`last_seen`** Stringified datetime attribute name of `object` that defines the time of the last activity. Takes a symbol. Defaults to `:last_seen`.
+
+**`statuses`** Array of all possible statuses. Takes an array of strings. Defaults to `['online', 'idle', 'offline', 'do not notify', 'do not disturb']`.
 
-**`do_not_notify_statuses`** Array of possible statuses that will prevent creating notifications for a target. Takes an array of strings. Defaults to `[]`.
+**`do_not_notify_statuses`** Array of possible statuses that will prevent creating notifications for a target. Takes an array of strings. Defaults to `['do not notify']`.
 
-**`do_not_push_statuses`** Array of possible statuses that will prevent pushing notifications of a target. Takes an array of strings. Defaults to `['do not disturb']`
+**`do_not_deliver_statuses`** Array of possible statuses that will prevent delivering notifications of a target. Takes an array of strings. Defaults to `['do not disturb']`
 
 ---
 
 ## To Do
 
-[Here](https://github.com/jonhue/notifications-rails/projects/4) is the full list of current projects.
+We use [GitHub projects](https://github.com/jonhue/notifications-rails/projects/4) to coordinate the work on this project.
 
 To propose your ideas, initiate the discussion by adding a [new issue](https://github.com/jonhue/notifications-rails/issues/new).
 
@@ -236,36 +311,6 @@ We hope that you will consider contributing to NotificationSettings. Please read
 
 [Learn more about contributing to this repository](https://github.com/jonhue/notifications-rails/blob/master/CONTRIBUTING.md), [Code of Conduct](https://github.com/jonhue/notifications-rails/blob/master/CODE_OF_CONDUCT.md)
 
-### Contributors
-
-Give the people some :heart: who are working on this project. See them all at:
-
-https://github.com/jonhue/notifications-rails/graphs/contributors
-
 ### Semantic Versioning
 
 NotificationSettings follows Semantic Versioning 2.0 as defined at http://semver.org.
-
-## License
-
-MIT License
-
-Copyright (c) 2017 Jonas Hübotter
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

data/app/models/notification_settings/subscription.rb

@@ -4,12 +4,11 @@ module NotificationSettings
   class Subscription < ActiveRecord::Base
     self.table_name = 'notification_settings_subscriptions'
 
-    include NotificationSettings::SubscriptionLibrary
+    include NotificationSettings::Settings
 
     belongs_to :subscriber, polymorphic: true
     belongs_to :subscribable, polymorphic: true
 
     has_many :notifications, class_name: '::Notification'
-    has_one :notification_setting, class_name: 'Setting'
   end
 end

data/lib/generators/notification_settings/install_generator.rb

@@ -19,7 +19,7 @@ module NotificationSettings
     end
 
     def create_initializer
-      template 'initializer.rb', 'config/initializers/notification-settings.rb'
+      template 'initializer.rb', 'config/initializers/notification_settings.rb'
     end
 
     def create_notifications_migration_file
@@ -34,6 +34,7 @@ module NotificationSettings
 
     def migration_version
       return unless Rails.version >= '5.0.0'
+
       "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
     end
   end

data/lib/generators/templates/install/initializer.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 NotificationSettings.configure do |config|
-  # Choose your default notification category. Takes a string.
-  # config.default_category = 'notification'
+  # An array of all notification categories. Takes an array of symbols.
+  # config.categories = [:notification]
+
+  # Choose your default notification category. Takes a symbol.
+  # config.default_category = :notification
 
   ### STATUS ###
 
@@ -15,14 +18,23 @@ NotificationSettings.configure do |config|
   # config.offline_after = 3.hours
 
   # Stringified datetime attribute name of `object` that defines the time of the
-  # last activity. Takes a string.
-  # config.last_seen = 'last_seen'
+  # last activity. Takes a symbol.
+  # config.last_seen = :last_seen
+
+  # Array of all possible statuses. Takes an array of strings.
+  # config.statuses = [
+  #   'online',
+  #   'idle',
+  #   'offline',
+  #   'do not notify',
+  #   'do not disturb'
+  # ]
 
   # Array of possible statuses that will prevent creating notifications for a
   # target. Takes an array of strings.
-  # config.do_not_notify_statuses = []
+  # config.do_not_notify_statuses = ['do not notify']
 
   # Array of possible statuses that will prevent pushing notifications of a
   # target. Takes an array of strings.
-  # config.do_not_push_statuses = ['do not disturb']
+  # config.do_not_deliver_statuses = ['do not disturb']
 end

data/lib/generators/templates/install/notifications_migration.rb.erb

@@ -5,21 +5,19 @@ class NotificationSettingsMigration < ActiveRecord::Migration<%= migration_versi
     add_column :notifications, :subscription_id, :bigint, index: true
     add_column :notifications, :category, :string, index: true
 
-    create_table :notification_settings_settings do |t|
-      t.references :object, polymorphic: true, index: { name: 'idx_settings_object_type_object_id' }
-      t.references :subscription, index: true
-
-      t.string :status
+    create_table :notification_settings_subscriptions do |t|
+      t.references :subscriber,
+                   polymorphic: true,
+                   index: {
+                     name: 'idx_subscriptions_subscriber_type_subscriber_id'
+                   }
+      t.references :subscribable,
+                   polymorphic: true,
+                   index: {
+                     name: 'idx_subscriptions_subscribable_type_subscribable_id'
+                   }
 
       t.text :settings
-      t.text :category_settings
-
-      t.timestamps
-    end
-
-    create_table :notification_settings_subscriptions do |t|
-      t.references :subscriber, polymorphic: true, index: { name: 'idx_subscriptions_subscriber_type_subscriber_id' }
-      t.references :subscribable, polymorphic: true, index: { name: 'idx_subscriptions_subscribable_type_subscribable_id' }
 
       t.timestamps
     end