noticed 1.2.0 → 1.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c8f1abe201518056e73f223b840bb30f44e173181116c632217f5f5a4a4b4d5
-  data.tar.gz: ba23af57eba01de7aecafd23c1ed00efacb8f354402592c68967f9f13c83a376
+  metadata.gz: 3a1534dc87f0c5a0ff1178c1eafc8babae3e4cd49f3f902311a4e7db9672ed77
+  data.tar.gz: a5e7f177a02369bc82a1ba3c5989df6b86ecfca2274c9f6905c8f14ca2e7537e
 SHA512:
-  metadata.gz: 32fcb3681980b2e0ad9db0cbd26e47c8ff8c4b4524f5c1068da010b967c46524dcee78ec3809e622791768a1be08793fc7c159dae061e028ff3e707f89fe6f47
-  data.tar.gz: f1d9d8318f4acb4ea77c8940f4e71bd91dd3ea40b70873741246109c472fc5164a5aa6be67fb22089b2bc6868601497c417ffb88cdb2e6ab92d1c195ab69ee58
+  metadata.gz: b6d5ae8fc80b975db5aaa09d33e9c35b55a0f8b02aee37cfc73c226357d3f80068d109b034006c563a19b581aa3a8b8d8600070e52a2e1eabe5d83ab76beb33e
+  data.tar.gz: 4f78b2bb15d8bf64f094b60905b5225abd431104bfb25271163748e9702cedac64bfd15640e9b3898f35f7375c57f8619ab48ccedc8d1f0cba6483fd683e9463

data/README.md

@@ -4,18 +4,27 @@
 
 ### 🎉  Notifications for your Ruby on Rails app.
 
-[![Build Status](https://github.com/excid3/noticed/workflows/Tests/badge.svg)](https://github.com/excid3/noticed/actions)
+[![Build Status](https://github.com/excid3/noticed/workflows/Tests/badge.svg)](https://github.com/excid3/noticed/actions) [![Gem Version](https://badge.fury.io/rb/noticed.svg)](https://badge.fury.io/rb/noticed)
 
 Currently, we support these notification delivery methods out of the box:
 
 * Database
 * Email
 * ActionCable channels
+* Slack
 * Twilio (SMS)
 * Vonage / Nexmo (SMS)
 
 And you can easily add new notification types for any other delivery methods.
 
+## 🎬 Screencast
+
+<div style="width:50%">
+  <a href="https://www.youtube.com/watch?v=Scffi4otlFc"><img src="https://i.imgur.com/UvVKWwD.png" title="How to add Notifications to Rails with Noticed" /></a>
+</div>
+
+[Watch Screencast](https://www.youtube.com/watch?v=Scffi4otlFc)
+
 ## 🚀 Installation
 Run the following command to add Noticed to your Gemfile
 
@@ -37,6 +46,28 @@ To generate a notification object, simply run:
 
 `rails generate noticed:notification CommentNotification`
 
+#### Sending Notifications
+
+To send a notification to a user:
+
+```ruby
+# Instantiate a new notification
+notification = CommentNotification.with(comment: @comment)
+
+# Deliver notification in background job
+notification.deliver_later(@comment.post.author)
+
+# Deliver notification immediately
+notification.deliver(@comment.post.author)
+
+# Deliver notification to multiple recipients
+notification.deliver_later(User.all)
+```
+
+This will instantiate a new notification with the `comment` stored in the notification's params.
+
+Each delivery method is able to transform this metadata that's best for the format. For example, the database may simply store the comment so it can be linked when rendering in the navbar. The websocket mechanism may transform this into a browser notification or insert it into the navbar.
+
 #### Notification Objects
 
 Notifications inherit from `Noticed::Base`. This provides all their functionality and allows them to be delivered.
@@ -49,10 +80,6 @@ class CommentNotification < Noticed::Base
   deliver_by :action_cable
   deliver_by :email, if: :email_notifications?
 
-  def email_notifications?
-    !!recipient.preferences[:email]
-  end
-
   # I18n helpers
   def message
     t(".message")
@@ -63,30 +90,16 @@ class CommentNotification < Noticed::Base
     post_path(params[:post])
   end
 
+  def email_notifications?
+    !!recipient.preferences[:email]
+  end
+
   after_deliver do
     # Anything you want
   end
 end
 ```
 
-#### Sending Notifications
-
-To send a notification to a user:
-
-```ruby
-notification = CommentNotification.with(comment: @comment.to_gid)
-
-# Deliver notification in background job
-notification.deliver_later(@comment.post.author)
-
-# Deliver notification immediately
-notification.deliver(@comment.post.author)
-```
-
-This will instantiate a new notification with the `comment` stored in the notification's params.
-
-Each delivery method is able to transform this metadata that's best for the format. For example, the database may simply store the comment so it can be linked when rendering in the navbar. The websocket mechanism may transform this into a browser notification or insert it into the navbar.
-
 **Shared Options**
 
 * `if: :method_name`  - Calls `method_name`and cancels delivery method if `false` is returned
@@ -131,7 +144,7 @@ Defining custom delivery methods allows you to add callbacks that run inside the
 
 ##### Translations
 
-We've added `translate` and  `t` helpers like Rails has to provide an easy way of scoping translations. If the key starts with a period, it will automatically scope the key under `notifications` and the underscored name of the notification class it is used in.
+We've added `translate` and `t` helpers like Rails has to provide an easy way of scoping translations. If the key starts with a period, it will automatically scope the key under `notifications` and the underscored name of the notification class it is used in.
 
 For example:
 
@@ -153,8 +166,6 @@ class CommentNotification < Noticed::Base
 end
 ```
 
-### 
-
 ## 🚛 Delivery Methods
 
 The delivery methods are designed to be modular so you can customize the way each type gets delivered.
@@ -175,6 +186,10 @@ Writes notification to the database.
 
   The name of the database association to use. Defaults to `:notifications`
 
+* `format: :format_for_database` - *Optional*
+
+  Use a custom method to define the attributes saved to the database
+
 ### Email
 
 Sends an email notification. Emails will always be sent with `deliver_later`
@@ -191,6 +206,10 @@ Sends an email notification. Emails will always be sent with `deliver_later`
 
   Used to customize the method on the mailer that is called
 
+* `format: :format_for_email` - *Optional*
+
+  Use a custom method to define the params sent to the mailer. `recipient` will be merged into the params.
+
 ### ActionCable
 
 Sends a notification to the browser via websockets (ActionCable channel by default).
@@ -263,7 +282,7 @@ Sends an SMS notification via Twilio.
 
 ### Vonage SMS
 
-Sends an SMS notification vai Vonage / Nexmo.
+Sends an SMS notification via Vonage / Nexmo.
 
 `deliver_by :vonage`
 
@@ -343,6 +362,45 @@ For Rails 6.0 and earlier, you must pass strings of the class names in the `deli
 
 We recommend the Rails 6.0 compatible options to prevent confusion.
 
+### 📦 Database Model
+
+The Notification database model includes several helpful features to make working with database notifications easier.
+
+#### Class methods
+
+Sorting notifications by newest first:
+
+```ruby
+user.notifications.newest_first
+```
+
+Marking all notifications as read:
+
+```ruby
+user.notifications.mark_as_read!
+```
+
+#### Instance methods
+
+Convert back into a Noticed notification object:
+
+```ruby
+@notification.to_notification
+```
+
+Mark notification as read:
+
+```ruby
+@notification.mark_as_read!
+```
+
+Check if read / unread:
+
+```ruby
+@notification.read?
+@notification.unread?
+```
+
 ## 🙏 Contributing
 
 This project uses [Standard](https://github.com/testdouble/standard) for formatting Ruby code. Please make sure to run `standardrb` before submitting pull requests.

data/lib/generators/noticed/templates/notification.rb.tt

@@ -22,6 +22,6 @@ class <%= class_name %> < Noticed::Base
   # end
   #
   # def url
-  #   posts_path(params[:post])
+  #   post_path(params[:post])
   # end
 end

data/lib/noticed.rb

@@ -1,3 +1,4 @@
+require "active_job/arguments"
 require "http"
 require "noticed/engine"
 

data/lib/noticed/base.rb

@@ -9,7 +9,8 @@ module Noticed
     class_attribute :delivery_methods, instance_writer: false, default: []
     class_attribute :param_names, instance_writer: false, default: []
 
-    attr_accessor :record
+    # Gives notifications access to the record and recipient when formatting for delivery
+    attr_accessor :record, :recipient
 
     class << self
       def deliver_by(name, options = {})
@@ -37,14 +38,24 @@ module Noticed
       @params = params
     end
 
-    def deliver(recipient)
+    def deliver(recipients)
       validate!
-      run_delivery(recipient, enqueue: false)
+
+      run_callbacks :deliver do
+        Array.wrap(recipients).uniq.each do |recipient|
+          run_delivery(recipient, enqueue: false)
+        end
+      end
     end
 
-    def deliver_later(recipient)
+    def deliver_later(recipients)
       validate!
-      run_delivery(recipient, enqueue: true)
+
+      run_callbacks :deliver do
+        Array.wrap(recipients).uniq.each do |recipient|
+          run_delivery(recipient, enqueue: true)
+        end
+      end
     end
 
     def params
@@ -55,18 +66,16 @@ module Noticed
 
     # Runs all delivery methods for a notification
     def run_delivery(recipient, enqueue: true)
-      run_callbacks :deliver do
-        delivery_methods = self.class.delivery_methods.dup
+      delivery_methods = self.class.delivery_methods.dup
 
-        # Run database delivery inline first if it exists so other methods have access to the record
-        if (index = delivery_methods.find_index { |m| m[:name] == :database })
-          delivery_method = delivery_methods.delete_at(index)
-          @record = run_delivery_method(delivery_method, recipient: recipient, enqueue: false)
-        end
+      # Run database delivery inline first if it exists so other methods have access to the record
+      if (index = delivery_methods.find_index { |m| m[:name] == :database })
+        delivery_method = delivery_methods.delete_at(index)
+        @record = run_delivery_method(delivery_method, recipient: recipient, enqueue: false)
+      end
 
-        delivery_methods.each do |delivery_method|
-          run_delivery_method(delivery_method, recipient: recipient, enqueue: enqueue)
-        end
+      delivery_methods.each do |delivery_method|
+        run_delivery_method(delivery_method, recipient: recipient, enqueue: enqueue)
       end
     end
 

data/lib/noticed/coder.rb

@@ -1,11 +1,13 @@
 module Noticed
   class Coder
     def self.load(data)
-      ActiveJob::Arguments.send(:deserialize_argument, data)
+      return if data.nil?
+      ActiveJob::Arguments.send(:deserialize_argument, JSON.parse(data))
     end
 
     def self.dump(data)
-      ActiveJob::Arguments.send(:serialize_argument, data)
+      return if data.nil?
+      ActiveJob::Arguments.send(:serialize_argument, data).to_json
     end
   end
 end

data/lib/noticed/delivery_methods/base.rb

@@ -4,15 +4,17 @@ module Noticed
       extend ActiveModel::Callbacks
       define_model_callbacks :deliver
 
-      attr_reader :notification, :options, :recipient
+      attr_reader :notification, :options, :recipient, :record
 
       def perform(notification_class:, options:, params:, recipient:, record:)
         @notification = notification_class.constantize.new(params)
         @options = options
         @recipient = recipient
+        @record = record
 
-        # Keep track of the database record for rendering
+        # Make notification aware of database record and recipient during delivery
         @notification.record = record
+        @notification.recipient = recipient
 
         run_callbacks :deliver do
           deliver

data/lib/noticed/delivery_methods/email.rb

@@ -2,7 +2,7 @@ module Noticed
   module DeliveryMethods
     class Email < Base
       def deliver
-        mailer.with(notification.params).send(method.to_sym).deliver_later
+        mailer.with(format).send(method.to_sym).deliver_later
       end
 
       private
@@ -14,6 +14,17 @@ module Noticed
       def method
         options[:method] || notification.class.name.underscore
       end
+
+      def format
+        if (method = options[:format])
+          notification.send(method)
+        else
+          notification.params.merge(
+            recipient: recipient,
+            record: record
+          )
+        end
+      end
     end
   end
 end

data/lib/noticed/version.rb

@@ -1,3 +1,3 @@
 module Noticed
-  VERSION = "1.2.0"
+  VERSION = "1.2.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noticed
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.5
 platform: ruby
 authors:
 - Chris Oliver
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-03 00:00:00.000000000 Z
+date: 2020-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails