acts_as_notifier 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b54dedfd2daec809d63e1158f2f8a6c0f7a3e1d1
+  data.tar.gz: 008889b4a39b1d0ce4db7bfe072c4d35f22f1031
+SHA512:
+  metadata.gz: 59b79b96dd4b6656d0efcec8bc4d5ceb165fd863b5eb45bcfc2d3e81c7245b00ab9f5e446db2ceff712c282682063720ede9f10e8061dcff797baab6d427e756
+  data.tar.gz: a482837b9a95c9778193e998dde01e867608529269e21844bbdb406c1fcfeaf046759ba29222d5d7a9000925b7c7742c2f8874e00871c0b2cd79e2132bfe7997

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Michael Johnson
+
+MIT License
+
+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/README.md

@@ -0,0 +1,186 @@
+# acts_as_notifier
+
+Easily define ActiveRecord callbacks that notify users of changes via email. Acts_as_notifier dries up your code with
+a simple, readable DSL, the ability to configure defaults, and by using delayed_job automatically if enabled. The DSL
+looks especially good when you have multiple notifications defined in a model.
+
+Instead of this:
+
+```ruby
+class MyModel < ActiveRecord::Base
+  def after_create
+    if alerts_enabled?
+      if MyMailer.respond_to?(:delay)
+        MyMailer.delay.new_widget_alert(get_recipients, self)
+      else
+        MyMailer.new_widget_alert(get_recipients, self).deliver
+      end
+    end
+  end
+end
+```
+
+With acts_as_notifier you write this:
+
+```ruby
+# in config/initializers/acts_as_notifier.rb
+ActsAsNotifier::Config.default_mailer = :MyMailer
+ActsAsNotifier::Config.default_mailer = :new_widget_alert
+
+class MyModel < ActiveRecord::Base
+  acts_as_notifier do
+    after_create do
+      notify :get_recipients, :if => :alerts_enabled?
+    end
+  end
+end
+```
+
+## When Should I Use This?
+
+Honestly, using an ActiveRecord callback to trigger email notifications is an [anti-pattern](#soapbox).
+Acts_as_notifier is a good solution when you have an existing Rails app, possibly with overly-complicated controllers,
+and refactoring is not feasible. In that case, acts_as_notifier gets you up and running quickly and hides some of the
+added complexity.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'acts_as_notifier'
+```
+
+And then execute:
+
+```ruby
+$ bundle
+```
+
+Or install it yourself as:
+
+```ruby
+$ gem install acts_as_notifier
+```
+
+## Usage
+
+```ruby
+# in config/initializers/acts_as_notifier.rb
+ActsAsNotifier::Config.default_mailer = :MyMailer
+ActsAsNotifier::Config.default_mailer = :change_notification
+
+# in app/models/my_model.rb
+class MyModel < ActiveRecord::Base
+  acts_as_notifier do
+    after_create do
+      notify recipients, options
+    end
+    after_update do
+      notify recipients, options
+    end
+    after_save do
+      notify recipients, options
+    end
+  end
+end
+
+# in app/mailers/my_mailer.rb
+class MyMailer < ActionMailer::Base
+  default from: 'test@example.com'
+
+  def change_notification(recipients, model)
+    mail(to: recipients, subject: "A #{model.class} with ID #{model.id} was changed")
+  end
+end
+```
+
+### recipients
+
+Can be a string containing email addresses, any object with an 'email' method, an array of strings/objects,
+or a proc or symbolic method name returning any of the above. Procs will be passed the options hash as a parameter.
+Note that to make sure you get the up-to-date recipients at runtime, you will normally use a proc.
+
+Examples:
+
+```ruby
+notify 'bob@somewhere.com', options
+notify :find_admin_users, options
+
+# note use of a proc to lazy-evaluate the ActiveRecord query
+notify Proc.new { User.where(:should_notify, true) }, options
+
+# pass yourself custom options in addition to the acts_as_notifiers options
+notify :get_recipients, :role => :admins
+def self.get_recipients(options)
+  User.find_all_by_role(options[:role])
+end
+```
+
+### options
+
+<table>
+<tr><td>:if</td><td>A string, proc, or name of a method that must evaluate to a truthy value in order for the notification to be sent. Procs and strings are evaluated in the context of the model instance. Procs are be passed the options hash as a parameter.</td></tr>
+<tr><td>:mailer</td><td>A class inheriting from ActionMailer::Base, may be a string or symbol or actual class.</td></tr>
+<tr><td>:method</td><td>Mailer method to invoke. Should accept recipients string and the ActiveRecord model as params.</td></tr>
+<tr><td>custom</td><td>Any additional options will be saved and passed to :if and recipients procs.</td></tr>
+</table>
+
+Examples:
+
+
+```ruby
+acts_as_notifier do
+  after_create do
+    # different ways of specifying :if condition
+    notify :recipients, :if => 'alerts_enabled?'
+    notify :recipients, :if => :alerts_enabled?
+    notify :recipients, :if => proc { alerts_enabled? }
+
+    # passing your own custom option to an if condition proc
+    notify :recipients, :if => proc {|opts| alerts_enabled_for_role?(opts[:role]) }, :role => :admin
+
+    # specifying a mailer
+    notify :recipients, :mailer => 'MyMailer'
+    notify :recipients, :mailer => :MyMailer
+    notify :recipients, :mailer => MyMailer
+
+    # specifying mailer method (in MyMailer class, def new_record_notification(recipients, model))
+    notify :recipients, :mailer => MyMailer, :method => :new_record_notification
+
+    # complete example
+    notify proc { User.where(wants_alerts: true) }, :if => :alerts_enabled?, :mailer => MyMailer, :method => :new_widget_alert
+  end
+                                                                                  x
+  # another complete example
+  after_save do
+    notify :owner, :if => ->(widget){ widget.broken? }, :mailer => MyMailer, :method => :broken_widget_alert
+  end
+end
+```
+
+## Configuration
+
+<table>
+<tr><td>ActsAsNotifier::Config.use_delayed_job=</td><td>true/false</td></tr>
+<tr><td>ActsAsNotifier::Config.default_mailer=</td><td>class inheriting from ActionMailer::Base</td></tr>
+<tr><td>ActsAsNotifier::Config.default_method=</td><td>mailer method to invoke, takes recipient string and ActiveRecord model as params</td></tr>
+<tr><td>ActsAsNotifier::Config.disabled=</td><td>true/false, can be globally enabled or disabled at any time</td></tr>
+</table>
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## <a name="soapbox"></a>Soapbox
+
+Why do I consider using ActiveRecord callbacks to trigger email notifications an anti-pattern? Callback-based behaviors
+are difficult to disable or isolate in testing and can result in mysterious, difficult-to-find bugs. In this particular
+case, using them violates the single responsibility principle in that a model should only be concerned with persisting
+your data. It also creates undesirable connections between your model, other models, and mailer classes. A better
+solution is to build business logic classes that handle creating and updating models, sending notifications, and are
+easier to isolate for testing.

data/Rakefile

@@ -0,0 +1,36 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ActsAsNotifier'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task :default => :test
+
+require "bundler/gem_tasks"

data/lib/acts_as_notifier.rb

@@ -0,0 +1,185 @@
+require "acts_as_notifier/version"
+require "acts_as_notifier/config"
+
+# Allows an ActiveRecord model to tie notification emails to create and save callbacks with conditions
+#
+# Usage:
+#   acts_as_notifier do
+#     after_create/save/update do
+#       notify recipients, options
+#     end
+#   end
+#
+# Params:
+#   recipients  - can be a string containing email addresses, any object with an 'email' method, an array of
+#                 strings/objects, or a proc or symbolic method name returning any of the above. procs will be
+#                 passed the options hash as a parameter.
+#
+#   options
+#     :if       - string to eval, proc, or method name, !!result must equal true for notification to be sent. procs will
+#                 be passed the options hash as a parameter.
+#     :mailer   - Typically a class inheriting from ActionMailer::Base.
+#                 May be any class or object with a method accepting a recipients string and instance of model that triggered the notification.
+#                 May also be a string or symbol that evals to a class or object.
+#     :method   - mailer class method to invoke, should accept recipient list and sending ActiveRecord model as params
+#     custom    - any additional options can be saved in the action and will be available to procs
+#
+# Examples:
+#   acts_as_notifier do
+#     after_create do
+#       notify proc { User.where(wants_alerts: true) }, :if => proc { send_alert? }, :mailer => MyMailer, :method => :new_widget_alert
+#     end
+#     after_save do
+#       notify :owner, :if => ->widget{ widget.broken? }, :mailer => MyMailer, :method => :broken_widget_alert
+#     end
+#   end
+#
+# Configuration:
+#   ActsAsNotifier::Config.use_delayed_job = true/false
+#   ActsAsNotifier::Config.default_mailer  = a class inheriting from ActionMailer::Base
+#   ActsAsNotifier::Config.default_method  = mailer class method to invoke, should accept recipient list and sending
+#                                            ActiveRecord model as params
+#   ActsAsNotifier::Config.disabled        = true/false, can be globally enabled or disabled at any time
+
+module ActsAsNotifier
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    def acts_as_notifier(&block)
+      cattr_accessor :notifier_actions
+      self.notifier_actions = NotificationDsl.evaluate(&block).presence || []
+      include LocalInstanceMethods
+    end
+  end
+
+  module LocalInstanceMethods
+    extend ActiveSupport::Concern
+
+    included do
+      after_create :notifier_create_handler
+      after_save   :notifier_save_handler
+      after_update :notifier_update_handler
+    end
+
+    # find a notification action matching options and trigger it, ignoring conditions
+    def force_notification(options = {})
+      opts = options.to_a
+      action = self.class.notifier_actions.find { |action| action.to_a & opts == opts }
+      notifier_send(action)
+    end
+
+    private
+
+    def notifier_create_handler
+      notifier_handler(:after_create) unless ActsAsNotifier::Config.disabled
+    end
+
+    def notifier_save_handler
+      notifier_handler(:after_save) unless ActsAsNotifier::Config.disabled
+    end
+
+    def notifier_update_handler
+      notifier_handler(:after_update) unless ActsAsNotifier::Config.disabled
+    end
+
+    def notifier_handler(callback_type)
+      self.class.notifier_actions.each do |action|
+        notifier_send(action) if action[:callback_type].to_sym == callback_type && notifier_conditions_satisfied?(action)
+      end
+    end
+
+    def notifier_conditions_satisfied?(action)
+      condition = action[:if]
+      condition = case condition
+        when String
+          instance_eval(condition)
+        when Proc
+          instance_exec(action, &condition)
+        when Symbol
+          self.send(condition)
+        when nil
+          true
+        else
+          condition
+      end
+      !!condition
+    end
+
+    def notifier_recipients(action)
+      recipients = action[:recipients]
+      recipients = case recipients
+        when Proc
+          instance_exec(action, &recipients)
+        when Symbol
+          self.send(recipients)
+        else
+          recipients
+      end
+      recipients = [ recipients ] unless recipients.is_a?(Array)
+      recipient_list = recipients.map {|r| r.respond_to?(:email) ? r.email : r }.join(', ')
+      recipient_list
+    end
+
+    def notifier_send(action)
+      if  (recipients = notifier_recipients(action)).present?
+        mailer, method = notifier_get_mailer(action)
+        if ActsAsNotifier::Config.use_delayed_job && mailer.respond_to?(:delay)
+          mailer.delay.send(method, recipients, self)
+        else
+          message = mailer.send(method, recipients, self)
+          message.deliver if message.respond_to?(:deliver)
+        end
+      end
+    end
+
+    def notifier_get_mailer(action)
+      mailer = action[:mailer] || ActsAsNotifier::Config.default_mailer
+      mailer = eval(mailer.to_s) if mailer.is_a?(String) || mailer.is_a?(Symbol)
+      raise "ActsAsNotifier invalid mailer configuration, mailer not specified" unless mailer.present?
+
+      method = action[:method] || ActsAsNotifier::Config.default_method
+      raise "ActsAsNotifier invalid mailer method configuration, method not specified" unless method.present?
+      raise "ActsAsNotifier invalid mailer method configuration, method must be a string or symbol" unless method.is_a?(String) || method.is_a?(Symbol)
+      raise "ActsAsNotifier invalid mailer method configuration, #{method} is not a valid method of #{mailer.to_s}" unless mailer.respond_to?(method)
+      return mailer, method
+    end
+  end
+
+  class NotificationDsl
+    attr_accessor :notification_actions
+
+    class << self
+      def evaluate(&script)
+        self.new.tap {|inst| inst.instance_eval(&script)}.notification_actions
+      end
+    end
+
+    def initialize
+      @current_callback_type = nil
+      @notification_actions = []
+    end
+
+    def after_create(&block)
+      @current_callback_type = :after_create
+      instance_eval(&block)
+    end
+
+    def after_save(&block)
+      @current_callback_type = :after_save
+      instance_eval(&block)
+    end
+
+    def after_update(&block)
+      @current_callback_type = :after_update
+      instance_eval(&block)
+    end
+
+    def notify(recipients, options = {})
+      action = { recipients: recipients, callback_type: @current_callback_type }.merge(options || {})
+      @notification_actions << action
+    end
+  end
+
+end
+
+ActiveRecord::Base.send(:include, ActsAsNotifier)

data/lib/acts_as_notifier/config.rb

@@ -0,0 +1,5 @@
+module ActsAsNotifier
+  module Config
+    mattr_accessor :use_delayed_job, :default_mailer, :default_method, :disabled
+  end
+end