noticed 1.2.11 → 1.2.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f215fc7642db8db6a38ba3354c4d58ad1621c6d6af5c4ee479a519fdab1fae8d
-  data.tar.gz: 874dc986fa682f54eaee86f0e8e638049cb8d4f310a2e4d906e76ba11b5d7405
+  metadata.gz: 3b37e7d17da790342493c2ffc575cc5d013ac156b7ac600fb0022c79bcb034de
+  data.tar.gz: 87fc46cbf6829e174b0dc6df1751187965e645f7461848469e48a2ea7bcb6a46
 SHA512:
-  metadata.gz: '039b85fe5977ecf3d3353ba275f0913f03a325a3affc913a5edc05f07e5555b38deff9fd23b492d16fbdaa58c0c5e3cf281267288c3ff69697d07e0ff840ded8'
-  data.tar.gz: 7a49698a38596e35382fffc86d12857414f9f8ecdbc68f2c66fd24e124e6b893f62f442e736d004c5fad0403aa55eecc30a749843c6a61b5f0fc45d1b9da84c2
+  metadata.gz: b9b4db6825f88670f27d768f40724fbd22c2f8e92fc6ce5f3bc32650cc9e77475d3c6eecb51fd7f59b10d70e735f648c92ecdae6f6d4b8ff61ff4b5c39e501d3
+  data.tar.gz: f474ad70283d4faa9b33bd51346acb64b29a4076b9c9c0ffcff58e60f75d331bc54b162a8e3d77310153d39caf898ac2924b234389b1089b3262b35fa7b48ac3

data/README.md

@@ -78,7 +78,7 @@ To add delivery methods, simply `include` the module for the delivery methods yo
 class CommentNotification < Noticed::Base
   deliver_by :database
   deliver_by :action_cable
-  deliver_by :email, if: :email_notifications?
+  deliver_by :email, mailer: 'CommentMailer', if: :email_notifications?
 
   # I18n helpers
   def message
@@ -86,6 +86,7 @@ class CommentNotification < Noticed::Base
   end
 
   # URL helpers are accessible in notifications
+  # Don't forget to set your default_url_options so Rails knows how to generate urls
   def url
     post_path(params[:post])
   end
@@ -113,6 +114,12 @@ You can define helper methods inside your Notification object to make it easier
 
 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.
 
+Don't forget, you'll need to configure `default_url_options` in order for Rails to know what host and port to use when generating URLs.
+
+```ruby
+Rails.application.routes.default_url_options[:host] = 'localhost:3000'
+```
+
 **Callbacks**
 
 Like ActiveRecord, notifications have several different types of callbacks.
@@ -120,7 +127,7 @@ Like ActiveRecord, notifications have several different types of callbacks.
 ```ruby
 class CommentNotification < Noticed::Base
   deliver_by :database
-  deliver_by :email
+  deliver_by :email, mailer: 'CommentMailer'
 
   # Callbacks for the entire delivery
   before_deliver :whatever
@@ -158,7 +165,7 @@ For example:
 
 ```ruby
 class CommentNotification < Noticed::Base
-  deliver_by :email, if: :email_notifications?
+  deliver_by :email, mailer: 'CommentMailer', if: :email_notifications?
 
   def email_notifications?
     recipient.email_notifications?
@@ -311,22 +318,28 @@ Sends an SMS notification via Vonage / Nexmo.
 
 ### 🚚 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`.
+To generate a custom delivery method, simply run
 
-```ruby
-class MyNotification < Noticed::Base
-  deliver_by :discord, class: "DiscordNotification"
-end
-```
+`rails generate noticed:delivery_method Discord`
+
+This will generate a new `DeliveryMethods::Discord` class inside the `app/notifications/delivery_methods` folder, which can be used to deliver notifications to Discord.
 
 ```ruby
-class DiscordNotification < Noticed::DeliveryMethods::Base
+class DeliveryMethods::Discord < Noticed::DeliveryMethods::Base
   def deliver
     # Logic for sending a Discord notification
   end
 end
 ```
 
+You can use the custom delivery method thus created by adding a `deliver_by` line with a unique name and `class` option in your notification class.
+
+```ruby
+class MyNotification < Noticed::Base
+  deliver_by :discord, class: "DeliveryMethods::Discord"
+end
+```
+
 Delivery methods have access to the following methods and attributes:
 
 * `notification` - The instance of the Notification. You can call methods on the notification to let the user easily override formatting and other functionality of the delivery method.
@@ -334,12 +347,51 @@ Delivery methods have access to the following methods and attributes:
 * `recipient` - The object who should receive the notification. This is typically a User, Account, or other ActiveRecord model.
 * `params` - The params passed into the notification. This is details about the event that happened. For example, a user commenting on a post would have params of `{ user: User.first }`
 
+#### Validating options passed to Custom Delivery methods
+
+The presence of the delivery method options is automatically validated if using the `option(s)` method.
+
+If you want to validate that the passed options contain valid values, or to add any custom validations, override the `self.validate!(delivery_method_options)` method from the `Noticed::DeliveryMethods::Base` class.
+
+```ruby
+class DeliveryMethods::Discord < Noticed::DeliveryMethods::Base
+  option :username # Requires the username option to be passed
+
+  def deliver
+    # Logic for sending a Discord notification
+  end
+
+  def self.validate!(delivery_method_options)
+    super # Don't forget to call super, otherwise option presence won't be validated
+
+    # Custom validations
+    if delivery_method_options[:username].blank?
+      raise Noticed::ValidationError, 'the `username` option must be present'
+    end
+  end
+end
+
+class CommentNotification < Noticed::Base
+  deliver_by :discord, class: 'DeliveryMethods::Discord'
+end
+```
+
+Now it will raise an error because a required argument is missing.
+
+To fix the error, the argument has to be passed correctly. For example:
+
+```ruby
+class CommentNotification < Noticed::Base
+  deliver_by :discord, class: 'DeliveryMethods::Discord', username: User.admin.username
+end
+```
+
 #### Callbacks
 
 Callbacks for delivery methods wrap the *actual* delivery of the notification. You can use `before_deliver`, `around_deliver` and `after_deliver` in your custom delivery methods.
 
 ```ruby
-class DiscordNotification < Noticed::DeliveryMethods::Base
+class DeliveryMethods::Discord < Noticed::DeliveryMethods::Base
   after_deliver do
     # Do whatever you want
   end
@@ -351,13 +403,13 @@ end
 Rails 6.1+ can serialize Class and Module objects as arguments to ActiveJob. The following syntax should work for Rails 6.1+:
 
 ```ruby
-  deliver_by DiscordNotification
+  deliver_by DeliveryMethods::Discord
 ```
 
-For Rails 6.0 and earlier, you must pass strings of the class names in the `deliver_by` options.
+For Rails 6.0, you must pass strings of the class names in the `deliver_by` options.
 
 ```ruby
-  deliver_by :discord, class: "DiscordNotification"
+  deliver_by :discord, class: "DeliveryMethods::Discord"
 ```
 
 We recommend the Rails 6.0 compatible options to prevent confusion.

data/lib/generators/noticed/delivery_method_generator.rb

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

data/lib/generators/noticed/model_generator.rb

@@ -15,13 +15,22 @@ module Noticed
       argument :attributes, type: :array, default: [], banner: "field:type field:type"
 
       def generate_notification
-        generate :model, name, "recipient:references{polymorphic}", "type", params_column, "read_at:datetime", *attributes
+        generate :model, name, "recipient:references{polymorphic}", "type", params_column, "read_at:datetime:index", *attributes
       end
 
       def add_noticed_model
         inject_into_class model_path, class_name, "  include Noticed::Model\n"
       end
 
+      def add_not_nullable
+        migration_path = Dir.glob(Rails.root.join("db/migrate/*")).max_by { |f| File.mtime(f) }
+
+        # Force is required because null: false already exists in the file and Thor isn't smart enough to tell the difference
+        insert_into_file migration_path, after: "t.string :type", force: true do
+          ", null: false"
+        end
+      end
+
       def done
         readme "README" if behavior == :invoke
       end
@@ -34,7 +43,7 @@ module Noticed
 
       def params_column
         case ActiveRecord::Base.configurations.configs_for(spec_name: "primary").config["adapter"]
-        when "mysql"
+        when "mysql2"
           "params:json"
         when "postgresql"
           "params:jsonb"

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

@@ -0,0 +1,12 @@
+class DeliveryMethods::<%= class_name %> < Noticed::DeliveryMethods::Base
+  def deliver
+    # Logic for sending the notification
+  end
+
+  # You may override this method to validate options for the delivery method
+  # Invalid options should raise a ValidationError
+  #
+  # def self.validate!(options)
+  #   raise ValidationError, "required_option missing" unless options[:required_option]
+  # end
+end

data/lib/noticed.rb

@@ -8,6 +8,7 @@ module Noticed
   autoload :Model, "noticed/model"
   autoload :TextCoder, "noticed/text_coder"
   autoload :Translation, "noticed/translation"
+  autoload :NotificationChannel, "noticed/notification_channel"
 
   module DeliveryMethods
     autoload :Base, "noticed/delivery_methods/base"

data/lib/noticed/base.rb

@@ -32,7 +32,7 @@ module Noticed
       def params(*names)
         param_names.concat Array.wrap(names)
       end
-      alias param params
+      alias_method :param, :params
     end
 
     def initialize(params = {})
@@ -97,13 +97,12 @@ module Noticed
       }
 
       run_callbacks delivery_method[:name] do
-        klass = get_class(delivery_method[:name], delivery_method[:options])
-        enqueue ? klass.perform_later(args) : klass.perform_now(args)
+        method = delivery_method_for(delivery_method[:name], delivery_method[:options])
+        enqueue ? method.perform_later(args) : method.perform_now(args)
       end
     end
 
-    # Retrieves the correct class for a delivery method
-    def get_class(name, options)
+    def delivery_method_for(name, options)
       if options[:class]
         options[:class].constantize
       else
@@ -111,13 +110,25 @@ module Noticed
       end
     end
 
-    # Validates that all params are present
     def validate!
+      validate_params_present!
+      validate_options_of_delivery_methods!
+    end
+
+    # Validates that all params are present
+    def validate_params_present!
       self.class.param_names.each do |param_name|
         if params[param_name].nil?
           raise ValidationError, "#{param_name} is missing."
         end
       end
     end
+
+    def validate_options_of_delivery_methods!
+      delivery_methods.each do |delivery_method|
+        method = delivery_method_for(delivery_method[:name], delivery_method[:options])
+        method.validate!(delivery_method[:options])
+      end
+    end
   end
 end

data/lib/noticed/delivery_methods/action_cable.rb

@@ -17,18 +17,18 @@ module Noticed
 
       def channel
         @channel ||= begin
-           value = options[:channel]
-           case value
-           when String
-             value.constantize
-           when Symbol
-             notification.send(value)
-           when Class
-             value
-           else
-             Noticed::NotificationChannel
-           end
-         end
+          value = options[:channel]
+          case value
+          when String
+            value.constantize
+          when Symbol
+            notification.send(value)
+          when Class
+            value
+          else
+            Noticed::NotificationChannel
+          end
+        end
       end
     end
   end

data/lib/noticed/delivery_methods/base.rb

@@ -4,11 +4,35 @@ module Noticed
       extend ActiveModel::Callbacks
       define_model_callbacks :deliver
 
-      attr_reader :notification, :options, :recipient, :record
+      class_attribute :option_names, instance_writer: false, default: []
+
+      attr_reader :notification, :options, :params, :recipient, :record
+
+      class << self
+        # Copy option names from parent
+        def inherited(base) #:nodoc:
+          base.option_names = option_names.dup
+          super
+        end
+
+        def options(*names)
+          option_names.concat Array.wrap(names)
+        end
+        alias_method :option, :options
+
+        def validate!(delivery_method_options)
+          option_names.each do |option_name|
+            unless delivery_method_options.key? option_name
+              raise ValidationError, "option `#{option_name}` must be set for #{name}"
+            end
+          end
+        end
+      end
 
       def perform(args)
         @notification = args[:notification_class].constantize.new(args[:params])
         @options = args[:options]
+        @params = args[:params]
         @recipient = args[:recipient]
         @record = args[:record]
 

data/lib/noticed/delivery_methods/email.rb

@@ -1,6 +1,8 @@
 module Noticed
   module DeliveryMethods
     class Email < Base
+      option :mailer
+
       def deliver
         mailer.with(format).send(method.to_sym).deliver_later
       end

data/lib/noticed/model.rb

@@ -32,10 +32,10 @@ module Noticed
     # 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
+        instance = type.constantize.with(params)
+        instance.record = self
+        instance
+      end
     end
 
     def mark_as_read!

data/lib/noticed/translation.rb

@@ -10,7 +10,7 @@ module Noticed
     def translate(key, **options)
       I18n.translate(scope_translation_key(key), **options)
     end
-    alias t translate
+    alias_method :t, :translate
 
     def scope_translation_key(key)
       if key.to_s.start_with?(".")

data/lib/noticed/version.rb

@@ -1,3 +1,3 @@
 module Noticed
-  VERSION = "1.2.11"
+  VERSION = "1.2.16"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noticed
 version: !ruby/object:Gem::Version
-  version: 1.2.11
+  version: 1.2.16
 platform: ruby
 authors:
 - Chris Oliver
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-08-20 00:00:00.000000000 Z
+date: 2020-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -91,10 +91,11 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
-- app/channels/noticed/notification_channel.rb
+- lib/generators/noticed/delivery_method_generator.rb
 - lib/generators/noticed/model_generator.rb
 - lib/generators/noticed/notification_generator.rb
 - lib/generators/noticed/templates/README
+- lib/generators/noticed/templates/delivery_method.rb.tt
 - lib/generators/noticed/templates/notification.rb.tt
 - lib/noticed.rb
 - lib/noticed/base.rb
@@ -109,6 +110,7 @@ files:
 - lib/noticed/delivery_methods/vonage.rb
 - lib/noticed/engine.rb
 - lib/noticed/model.rb
+- lib/noticed/notification_channel.rb
 - lib/noticed/text_coder.rb
 - lib/noticed/translation.rb
 - lib/noticed/version.rb
@@ -117,7 +119,7 @@ homepage: https://github.com/excid3/noticed
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -132,8 +134,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.1.4
+signing_key:
 specification_version: 4
 summary: Notifications for Ruby on Rails applications
 test_files: []