acts_as_newsletter 0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+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,81 @@
+# Acts as Newsletter
+
+This gem allows you to quickly implement a newsletter model without coding the
+whole model management logic.
+
+## Installation
+
+Just add the gem to your Gemfile and bundle :
+
+```ruby
+gem "acts_as_newsletter"
+```
+
+To configure it, if needed, you can generate the default initializer with :
+
+```bash
+rails generate acts_as_newsletter:install
+```
+
+## Usage
+
+Use the generator to generate the migration for your model :
+
+```bash
+# If your model is Newsletter
+rails generate acts_as_newsletter newsletter
+```
+
+Now just add the `acts_as_newsletter` macro in your model, passing it a block
+which returns a list of e-mail addresses to which the newsletter will be sent.
+
+The block is passed the current Newsletter object so you can configure the way
+emails are retrieved for each different newsletter :
+
+```ruby
+class Newsletter < ActiveRecord::Base
+  belongs_to :emails_list
+
+  acts_as_newsletter do |newsletter|
+    emails newsletter.emails_list.emails.pluck(:email)
+    # Assuming your mailer views are in app/views/newsletters/
+    template_path "newsletters"
+    # Set newsletters/newsletter.(html|text).erb
+    layout "newsletter"
+    # Get your mail template dynamically
+    template_name newsletter.type.template
+  end
+end
+```
+
+## Sending it
+
+Let's suppose you configured your `Newsletter` model, and created your mailer
+view file, so everything is ready to be sent.
+
+All what you need to do is to use the provided default rake task :
+
+```bash
+rake acts_as_newsletter:send_next
+```
+
+But wait ... it doesn't do anything by default since we can't know which model
+is actually a newsletter - well we don't want `acts_as_newsletter` to know it -
+and your sending logic may be custom. So the easiest way to configure it is to
+uncomment the specified block in your
+`config/initializers/acts_as_newsletter.rb` file and define your logic, or let
+the default here :
+
+```ruby
+config.send_next = proc {
+  Newsletter.send_next!
+}
+```
+
+Now run `rake acts_as_newsletter:send_next` and it should send your e-mails !
+
+
+## Licence
+
+It uses MIT Licence so you can do whatever you want with it
+

data/Rakefile

@@ -0,0 +1,35 @@
+#!/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    = 'ActsAsNewsletter'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+Dir[File.expand_path "../lib/tasks/*", __FILE__].each do |task_file|
+  load task_file
+end
+
+task :default => :spec

data/lib/acts_as_newsletter.rb

@@ -0,0 +1,32 @@
+module ActsAsNewsletter
+  mattr_accessor :send_next
+
+  class Config
+    # Define classes config accessors
+    %w(model mailer).each do |method|
+      define_method(method) do
+        ActsAsNewsletter.const_get(method.camelize)
+      end
+    end
+
+    def initialize &block
+      block.call(self) if block_given?
+    end
+
+    def method_missing method, *args, &block
+      if ActsAsNewsletter.respond_to?(method)
+        ActsAsNewsletter.send(method, *args, &block)
+      else
+        super method, *args, &block
+      end
+    end
+  end
+
+  def self.config &block
+    yield Config.new(&block) if block_given?
+  end
+end
+
+require 'acts_as_newsletter/model'
+require 'acts_as_newsletter/mailer'
+require 'acts_as_newsletter/railtie' if defined?(Rails)

data/lib/acts_as_newsletter/mailer.rb

@@ -0,0 +1,20 @@
+module ActsAsNewsletter
+  class Mailer < ActionMailer::Base
+    # Allows setting a general <From> header by configuring it in the
+    # initializer
+    #
+    cattr_accessor :from
+
+    # Sends the actual newsletter to the specified email
+    #
+    def newsletter newsletter, email, mail_config
+      @newsletter = newsletter
+      @email = email
+      mail mail_config.merge(
+        to: email,
+        subject: newsletter.subject,
+        from: (mail_config[:from] or from)
+      )
+    end
+  end
+end

data/lib/acts_as_newsletter/model.rb

@@ -0,0 +1,155 @@
+require 'acts_as_newsletter/model/config'
+require 'state_machine'
+
+# Module allowing to simply configure a model to be sent as a newsletter
+# It can be mixed in an ActiveRecord model by calling the `acts_as_newsletter`
+# macro directly in your class' body
+#
+# @example
+#   class Newsletter < ActiveRecord::Base
+#     acts_as_newsletter do |newsletter|
+#       emails newsletter.emails
+#       template_path "emails"
+#       template_name "newsletter"
+#       layout false
+#     end
+#   end
+#
+module ActsAsNewsletter
+  module Model
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      attr_reader :config_proc
+
+      def acts_as_newsletter &config
+        # Store config proc to be dynamically run when sending a newsletter
+        @config_proc = config
+
+        # Define state machine
+        class_eval do
+          state_machine :state, initial: :draft do
+
+            event :written do
+              transition draft: :ready
+            end
+
+            event :ready_canceled do
+              transition ready: :draft
+            end
+
+            event :prepare_sending do
+              transition ready: :sending
+            end
+            before_transition on: :prepare_sending, do: :prepare_emails
+
+            event :sending_complete do
+              transition sending: :sent
+            end
+
+            state :draft do
+              # If readied is set to true, then we transition to the `ready`
+              # state so it can be matched when calling `::next_newsletter`
+              before_validation do
+                written! if readied
+              end
+            end
+
+            state :ready do
+              before_validation do
+                ready_canceled! if !readied
+              end
+            end
+
+            state :sending do
+              # When we're sending, saving serializes current emails list
+              # to only store remaining recipients and updates sent counter
+              #
+              before_validation do
+                if chunk_sent
+                  self.recipients = emails.join("|")
+                  self.sent_count += emails.length
+                  # Transition to :sent state when complete
+                  sending_complete! if sent_count == recipients_count
+                end
+              end
+
+              # Avoids multiple calls to save to run into the above
+              # before_validation hook without the next chunk being really sent
+              #
+              after_save do
+                self.chunk_sent = false if chunk_sent
+                @emails = nil
+              end
+            end
+          end
+        end
+      end
+
+      # Send next newsletter if one is ready
+      #
+      def send_next!
+        (newsletter = next_newsletter) and newsletter.send_newsletter!
+      end
+
+      # Finds first newsletter being sent or ready
+      #
+      def next_newsletter
+        where(state: :sending).first or where(state: :ready).first
+      end
+    end
+
+    # Emails chunk size to send at a time
+    #
+    mattr_accessor :emails_chunk_size
+    self.emails_chunk_size = 500
+
+    # Boolean allowing us to know if we sent the last emails chunk
+    #
+    attr_accessor :chunk_sent
+
+    # Newsletter configuration passed to the block
+    def newsletter_config
+      @newsletter_config ||=
+        Model::Config.new(self, &self.class.config_proc).config
+    end
+
+
+    # Prepare model to handle e-mail sending collecting e-mails and
+    # initializing counters
+    #
+    def prepare_emails
+      emails_list = newsletter_config[:emails]
+      self.recipients_count = emails_list.length
+      self.sent_count = 0
+      self.recipients = emails_list.join("|")
+    end
+
+    # Parses all available e-mails stored in recpients field
+    def available_emails
+      @available_emails ||= recipients.split("|")
+    end
+
+    # Takes emails from the list and delete them from it
+    def emails
+      @emails ||= available_emails.shift(emails_chunk_size)
+    end
+
+    def send_newsletter!
+      prepare_sending! if state_name == :ready
+      # Get config from newsletter config
+      mail_config_keys = [:template_path, :template_name, :layout, :from]
+      config = newsletter_config.select do |key, value|
+        mail_config_keys.include?(key) and value
+      end
+
+      # Send e-mail to each recipient
+      emails.each do |email|
+        ActsAsNewsletter::Mailer.newsletter(self, email, config).deliver
+      end
+
+      self.chunk_sent = true
+      save
+    end
+  end
+end

data/lib/acts_as_newsletter/model/config.rb

@@ -0,0 +1,21 @@
+module ActsAsNewsletter
+  module Model
+    class Config
+      attr_reader :config, :model
+
+      def initialize model, &block
+        # Initialize config default values
+        @config = { emails: [], layout: false }
+        @model = model
+        # Eval block to edit config
+        instance_eval &block if block_given?
+      end
+
+      %w(emails template_path template_name layout from).each do |method|
+        define_method method do |value|
+          @config[method.to_sym] = value
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_newsletter/railtie.rb

@@ -0,0 +1,19 @@
+require 'acts_as_newsletter'
+
+module ActsAsNewsletter
+  require 'rails'
+
+  class Railtie < Rails::Railtie
+    initializer 'acts_as_newsletter.insert_into_active_record' do |app|
+      ActiveSupport.on_load :active_record do
+        ActiveRecord::Base.send(:include, ActsAsNewsletter::Model)
+      end
+
+      ActiveSupport.on_load :action_controller do
+        ActsAsNewsletter::Mailer.send(:add_template_helper, ::ApplicationHelper)
+      end
+    end
+
+    rake_tasks { load "tasks/acts_as_newsletter.rake" }
+  end
+end

data/lib/acts_as_newsletter/version.rb

@@ -0,0 +1,3 @@
+module ActsAsNewsletter
+  VERSION = "0.1"
+end

data/lib/generators/acts_as_newsletter/acts_as_newsletter_generator.rb

@@ -0,0 +1,35 @@
+require 'rails/generators/active_record'
+
+class ActsAsNewsletterGenerator < ActiveRecord::Generators::Base
+  # Copied files come from templates folder
+  source_root File.expand_path('../templates', __FILE__)
+
+  # Generator desc
+  desc "ActsAsNewsletter install generator"
+
+  def generate_migration
+    migration_template "migration.erb", "db/migrate/#{ migration_file_name }"
+  end
+
+  def notice
+    say " ** Migration created, now just add `acts_as_newsletter` macro to your #{ camelized_model } model"
+  end
+
+  private
+
+  def camelized_model
+    name.camelize
+  end
+
+  def migration_name
+    "add_acts_as_newsletter_to_#{ name.pluralize }"
+  end
+
+  def migration_file_name
+    "#{ migration_name }.rb"
+  end
+
+  def migration_class_name
+    migration_name.camelize
+  end
+end

data/lib/generators/acts_as_newsletter/install/install_generator.rb

@@ -0,0 +1,12 @@
+module ActsAsNewsletter
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      # Copied files come from templates folder
+      source_root File.expand_path('../templates', __FILE__)
+
+      def copy_initializer
+        copy_file "initializer.rb", "config/initializers/acts_as_newsletter.rb"
+      end
+    end
+  end
+end