noticed 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8ce628657c8b6011616fbcf075869fe902ad33f19569acadf88e52aef89fb79
-  data.tar.gz: f92330969818566ce0d4080341f19631be41fd5bb4c45f94dfb3ab5714c3c663
+  metadata.gz: 5c8f1abe201518056e73f223b840bb30f44e173181116c632217f5f5a4a4b4d5
+  data.tar.gz: ba23af57eba01de7aecafd23c1ed00efacb8f354402592c68967f9f13c83a376
 SHA512:
-  metadata.gz: 8945414df8ed4cdf89bbf654171e686b8c655ae91542177207f134052d0d09794df146192694775f9e755a3b0a65fafbe180130d41590f186b53837c9f114961
-  data.tar.gz: c78d5048f9fb95b6982dc44edd7fa03d8f2cf8cf093884d059668fb2aed3258d9f2992b84b2843ac61e39d3e3ce42818fc48c583520d2097cb89bf8260b1aa30
+  metadata.gz: 32fcb3681980b2e0ad9db0cbd26e47c8ff8c4b4524f5c1068da010b967c46524dcee78ec3809e622791768a1be08793fc7c159dae061e028ff3e707f89fe6f47
+  data.tar.gz: f1d9d8318f4acb4ea77c8940f4e71bd91dd3ea40b70873741246109c472fc5164a5aa6be67fb22089b2bc6868601497c417ffb88cdb2e6ab92d1c195ab69ee58

data/README.md

@@ -1,4 +1,8 @@
-# Noticed - Notifications for your Ruby on Rails app.
+<p align="center">
+  <h1>Noticed</h1>
+</p>
+
+### 🎉  Notifications for your Ruby on Rails app.
 
 [![Build Status](https://github.com/excid3/noticed/workflows/Tests/badge.svg)](https://github.com/excid3/noticed/actions)
 
@@ -6,32 +10,38 @@ Currently, we support these notification delivery methods out of the box:
 
 * Database
 * Email
-* Websocket (realtime)
+* ActionCable channels
 * 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:
+## 🚀 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.
 
-Or install it yourself as:
-```bash
-$ gem install noticed
+```ruby
+rails generate noticed:model
 ```
 
-## Usage
+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`
+
+#### Notification Objects
+
+Notifications inherit from `Noticed::Base`. This provides all their functionality and allows them to be delivered.
 
-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.
+To add delivery methods, simply `include` the module for the delivery methods you would like to use.
 
 ```ruby
 class CommentNotification < Noticed::Base
@@ -42,13 +52,25 @@ class CommentNotification < Noticed::Base
   def email_notifications?
     !!recipient.preferences[:email]
   end
-  
+
+  # I18n helpers
+  def message
+    t(".message")
+  end
+
+  # URL helpers are accessible in notifications
+  def url
+    post_path(params[:post])
+  end
+
   after_deliver do
     # Anything you want
   end
 end
 ```
 
+#### Sending Notifications
+
 To send a notification to a user:
 
 ```ruby
@@ -61,15 +83,23 @@ notification.deliver_later(@comment.post.author)
 notification.deliver(@comment.post.author)
 ```
 
-This will instantiate a new notification with the `comment` global ID stored in the metadata.
+This will instantiate a new notification with the `comment` stored in the notification's params.
 
-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.
+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
 * `unless: :method_name`  - Calls `method_name`and cancels delivery method if `true` is returned
 
+##### Helper Methods
+
+You can define helper methods inside your Notification object to make it easier to render.
+
+##### URL Helpers
+
+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**
 
 Like ActiveRecord, notifications have several different types of callbacks.
@@ -78,11 +108,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 +129,35 @@ 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`
+
+##### 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
+```
 
-The delivery methods are designed to be overriden so that you can customi1ze the notification for each medium.
+### 
+
+## 🚛 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 +169,12 @@ 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`
+
 ### Email
 
 Sends an email notification. Emails will always be sent with `deliver_later`
@@ -228,23 +290,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 +343,9 @@ 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.
+## 🙏 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
+  #   posts_path(params[:post])
+  # end
+end

data/lib/noticed.rb

@@ -4,6 +4,8 @@ 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,5 +1,8 @@
 module Noticed
   class Base
+    include Translation
+    include Rails.application.routes.url_helpers
+
     extend ActiveModel::Callbacks
     define_model_callbacks :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/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.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: noticed
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Chris Oliver
@@ -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