noticed 1.1.0 → 1.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8ce628657c8b6011616fbcf075869fe902ad33f19569acadf88e52aef89fb79
-  data.tar.gz: f92330969818566ce0d4080341f19631be41fd5bb4c45f94dfb3ab5714c3c663
+  metadata.gz: 2936d217d3d881874888d8dd68280ecc9888f41fc1edf3f195e713bf863d2233
+  data.tar.gz: a73fba77cb4eebead7c3d343c501cbe7ca5b19db5a24b11b6d33e6674c41a1f9
 SHA512:
-  metadata.gz: 8945414df8ed4cdf89bbf654171e686b8c655ae91542177207f134052d0d09794df146192694775f9e755a3b0a65fafbe180130d41590f186b53837c9f114961
-  data.tar.gz: c78d5048f9fb95b6982dc44edd7fa03d8f2cf8cf093884d059668fb2aed3258d9f2992b84b2843ac61e39d3e3ce42818fc48c583520d2097cb89bf8260b1aa30
+  metadata.gz: 67f055f8a05d3418caf3c21c2a3938341705752e6154284bbe596ac31563fd715c7d29d5651f690ce310433d762b7dca05e99ec8326b93d477a85db91cddfd10
+  data.tar.gz: 3fbaf13b4dd6f7f3fa9f50a52849ef0ff112268c730cdca202f2e421fd7f66cdc797147c549911addb2161ed2c40d7738d6d85e5d420427f46658eaef5b13b81

data/README.md

@@ -1,37 +1,78 @@
-# Noticed - Notifications for your Ruby on Rails app.
+<p align="center">
+  <h1>Noticed</h1>
+</p>
 
-[![Build Status](https://github.com/excid3/noticed/workflows/Tests/badge.svg)](https://github.com/excid3/noticed/actions)
+### 🎉  Notifications for your Ruby on Rails app.
+
+[![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
-* Websocket (realtime)
+* ActionCable channels
+* Slack
 * Twilio (SMS)
 * Vonage / Nexmo (SMS)
 
 And you can easily add new notification types for any other delivery methods.
 
-## Installation
-Add this line to your application's Gemfile:
+## 🎬 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
 
 ```ruby
-gem 'noticed'
+bundle add "noticed"
 ```
 
-And then execute:
-```bash
-$ bundle
+To save notifications to your database, use the following command to generate a Notification model.
+
+```ruby
+rails generate noticed:model
 ```
 
-Or install it yourself as:
-```bash
-$ gem install noticed
+This will generate a Notification model and instructions for associating User models with the notifications table.
+
+## 📝 Usage
+
+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)
 ```
 
-## Usage
+This will instantiate a new notification with the `comment` stored in the notification's params.
 
-You can define a Notification as a class that inherits from Noticed::Base. To add delivery methods, simply `include` the module for the delivery methods you would like to use.
+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.
+
+To add delivery methods, simply `include` the module for the delivery methods you would like to use.
 
 ```ruby
 class CommentNotification < Noticed::Base
@@ -39,36 +80,38 @@ class CommentNotification < Noticed::Base
   deliver_by :action_cable
   deliver_by :email, if: :email_notifications?
 
+  # I18n helpers
+  def message
+    t(".message")
+  end
+
+  # URL helpers are accessible in notifications
+  def url
+    post_path(params[:post])
+  end
+
   def email_notifications?
     !!recipient.preferences[:email]
   end
-  
+
   after_deliver do
     # Anything you want
   end
 end
 ```
 
-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)
+**Shared Options**
 
-# Deliver notification immediately
-notification.deliver(@comment.post.author)
-```
+* `if: :method_name`  - Calls `method_name`and cancels delivery method if `false` is returned
+* `unless: :method_name`  - Calls `method_name`and cancels delivery method if `true` is returned
 
-This will instantiate a new notification with the `comment` global ID stored in the metadata.
+##### Helper Methods
 
-Each delivery method is able to transfrom 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.
+You can define helper methods inside your Notification object to make it easier to render.
 
-**Shared Options**
+##### URL Helpers
 
-* `if: :method_name`  - Calls `method_name`and cancels delivery method if `false` is returned
-* `unless: :method_name`  - Calls `method_name`and cancels delivery method if `true` is returned
+Rails url helpers are included in notification classes by default so you have full access to them just like you would in your controllers and views.
 
 **Callbacks**
 
@@ -78,11 +121,11 @@ Like ActiveRecord, notifications have several different types of callbacks.
 class CommentNotification < Noticed::Base
   deliver_by :database
   deliver_by :email
-  
+
   # Callbacks for the entire delivery
   before_deliver :whatever
   around_deliver :whatever
-  after_deliver :whatever 
+  after_deliver :whatever
 
   # Callbacks for each delivery method
   before_database :whatever
@@ -99,9 +142,33 @@ When using `deliver_later` callbacks will be run around queuing the delivery met
 
 Defining custom delivery methods allows you to add callbacks that run inside the background job as each individual delivery is executed. See the Custom Delivery Methods section for more information.
 
-## Delivery Methods
+##### 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.
+
+For example:
+
+ `t(".message")` looks up `en.notifications.new_comment.message`
 
-The delivery methods are designed to be overriden so that you can customi1ze the notification for each medium.
+##### User Preferences
+
+You can use the `if:` and `unless: ` options on your delivery methods to check the user's preferences and skip processing if they have disabled that type of notification.
+
+For example:
+
+```ruby
+class CommentNotification < Noticed::Base
+  deliver_by :email, if: :email_notifications?
+
+  def email_notifications?
+    recipient.email_notifications?
+  end
+end
+```
+
+## 🚛 Delivery Methods
+
+The delivery methods are designed to be modular so you can customize the way each type gets delivered.
 
 For example, emails will require a subject, body, and email address while an SMS requires a phone number and simple message. You can define the formats for each of these in your Notification and the delivery method will handle the processing of it.
 
@@ -113,6 +180,16 @@ Writes notification to the database.
 
 **Note:** Database notifications are special in that they will run before the other delivery methods. We do this so you can reference the database record ID in other delivery methods.
 
+##### Options
+
+* `association` - *Optional*
+
+  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`
@@ -129,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).
@@ -201,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`
 
@@ -228,23 +309,7 @@ Sends an SMS notification vai Vonage / Nexmo.
   }
   ```
 
-### User Preferences
-
-Each delivery method implements a `deliver_with_#{name}` method that receives the recipient as the first argument. You can override this method to check the user's preferences and skip processing if they have disabled that type of notification.
-
-For example:
-
-```ruby
-class CommentNotification < Noticed::Base
-  deliver_by :email, if: :email_notifications?
-
-  def email_notifications?
-    recipient.email_notifications?
-  end
-end
-```
-
-### Custom Delivery Methods
+### 🚚 Custom Delivery Methods
 
 You can define a custom delivery method easily by adding a `deliver_by` line with a unique name and class option. The class will be instantiated and should inherit from `Noticed::DeliveryMethods::Base`.
 
@@ -297,8 +362,48 @@ 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.
 
-## Contributing
-Contribution directions go here.
+### 📦 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.
 
-## License
+## 📝 License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/generators/noticed/model_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Noticed
+  module Generators
+    class ModelGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::ResourceHelpers
+
+      source_root File.expand_path("../templates", __FILE__)
+
+      desc "Generates a Notification model for storing notifications."
+
+      argument :name, type: :string, default: "Notification", banner: "Notification"
+      argument :attributes, type: :array, default: [], banner: "field:type field:type"
+
+      def generate_notification
+        generate :model, name, "recipient:references{polymorphic}", "type", "params:text", "read_at:datetime", *attributes
+      end
+
+      def add_noticed_model
+        inject_into_class model_path, class_name, "  include Noticed::Model\n"
+      end
+
+      def done
+        readme "README" if behavior == :invoke
+      end
+
+      private
+
+      def model_path
+        @model_path ||= File.join("app", "models", "#{file_path}.rb")
+      end
+    end
+  end
+end

data/lib/generators/noticed/notification_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Noticed
+  module Generators
+    class NotificationGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::ResourceHelpers
+
+      source_root File.expand_path("../templates", __FILE__)
+
+      desc "Generates a notification with the given NAME."
+
+      def generate_notification
+        template "notification.rb", "app/notifications/#{singular_name}.rb"
+      end
+    end
+  end
+end

data/lib/generators/noticed/templates/README

@@ -0,0 +1,7 @@
+
+🚚 Your notifications database model has been generated!
+
+Next steps:
+1. Run "rails db:migrate"
+2. Add "has_many :notifications, as: :recipient" to your User model(s).
+3. Generate notifications with "rails g noticed:notification"

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

@@ -0,0 +1,27 @@
+# To deliver this notification:
+#
+# <%= class_name %>.with(post: @post).deliver_later(current_user)
+# <%= class_name %>.with(post: @post).deliver(current_user)
+
+class <%= class_name %> < Noticed::Base
+  # Add your delivery methods
+  #
+  # deliver_by :database
+  # deliver_by :email, mailer: "UserMailer"
+  # deliver_by :slack
+  # deliver_by :custom, class: "MyDeliveryMethod"
+
+  # Add required params
+  #
+  # param :post
+
+  # Define helper methods to make rendering easier.
+  #
+  # def message
+  #   t(".message")
+  # end
+  #
+  # def url
+  #   post_path(params[:post])
+  # end
+end

data/lib/noticed.rb

@@ -1,9 +1,12 @@
+require "active_job/arguments"
 require "http"
 require "noticed/engine"
 
 module Noticed
   autoload :Base, "noticed/base"
   autoload :Coder, "noticed/coder"
+  autoload :Model, "noticed/model"
+  autoload :Translation, "noticed/translation"
 
   module DeliveryMethods
     autoload :Base, "noticed/delivery_methods/base"

data/lib/noticed/base.rb

@@ -1,12 +1,16 @@
 module Noticed
   class Base
+    include Translation
+    include Rails.application.routes.url_helpers
+
     extend ActiveModel::Callbacks
     define_model_callbacks :deliver
 
     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 = {})
@@ -34,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
@@ -52,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/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/database.rb

@@ -3,11 +3,15 @@ module Noticed
     class Database < Base
       # Must return the database record
       def deliver
-        recipient.notifications.create(attributes)
+        recipient.send(association_name).create!(attributes)
       end
 
       private
 
+      def association_name
+        options[:association] || :notifications
+      end
+
       def attributes
         if (method = options[:format])
           notification.send(method)

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/model.rb

@@ -0,0 +1,42 @@
+module Noticed
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      self.inheritance_column = nil
+
+      serialize :params, Noticed::Coder
+
+      belongs_to :recipient, polymorphic: true
+
+      scope :newest_first, -> { order(created_at: :desc) }
+    end
+
+    module ClassMethods
+      def mark_as_read!
+        update_all(read_at: Time.current, updated_at: Time.current)
+      end
+    end
+
+    # Rehydrate the database notification into the Notification object for rendering
+    def to_notification
+      @_notification ||= begin
+                      instance = type.constantize.with(params)
+                      instance.record = self
+                      instance
+                    end
+    end
+
+    def mark_as_read!
+      update(read_at: Time.current)
+    end
+
+    def unread?
+      !read?
+    end
+
+    def read?
+      read_at?
+    end
+  end
+end

data/lib/noticed/translation.rb

@@ -0,0 +1,21 @@
+module Translation
+  extend ActiveSupport::Concern
+
+  # Returns the +i18n_scope+ for the class. Overwrite if you want custom lookup.
+  def i18n_scope
+    :notifications
+  end
+
+  def translate(key, **options)
+    I18n.translate(scope_translation_key(key), **options)
+  end
+  alias t translate
+
+  def scope_translation_key(key)
+    if key.to_s.start_with?(".")
+      "notifications.#{self.class.name.underscore}#{key}"
+    else
+      key
+    end
+  end
+end

data/lib/noticed/version.rb

@@ -1,3 +1,3 @@
 module Noticed
-  VERSION = "1.1.0"
+  VERSION = "1.2.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noticed
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.4
 platform: ruby
 authors:
 - Chris Oliver
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-03 00:00:00.000000000 Z
+date: 2020-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -92,6 +92,10 @@ files:
 - README.md
 - Rakefile
 - app/channels/noticed/notification_channel.rb
+- lib/generators/noticed/model_generator.rb
+- lib/generators/noticed/notification_generator.rb
+- lib/generators/noticed/templates/README
+- lib/generators/noticed/templates/notification.rb.tt
 - lib/noticed.rb
 - lib/noticed/base.rb
 - lib/noticed/coder.rb
@@ -104,6 +108,8 @@ files:
 - lib/noticed/delivery_methods/twilio.rb
 - lib/noticed/delivery_methods/vonage.rb
 - lib/noticed/engine.rb
+- lib/noticed/model.rb
+- lib/noticed/translation.rb
 - lib/noticed/version.rb
 - lib/tasks/noticed_tasks.rake
 homepage: https://github.com/excid3/noticed