padrino-mailer 0.9.10 → 0.9.11

data/README.rdoc

@@ -2,60 +2,100 @@
 
 === Overview
 
-This component uses an enhanced version of the excellent <tt>pony</tt> library (vendored) for a powerful but simple
-mailer system within Padrino (and Sinatra). There is full support for using an html content type as well as for file attachments.
-The MailerPlugin has many similarities to ActionMailer but is much lighterweight and (arguably) easier to use.
+This component creates an easy and intuitive interface for delivering email within a Sinatra application. The mail library is utilized
+to do the bulk of the work. There is full support for rendering email templates, using an html content type and for file attachments.
+The Padrino Mailer uses a familiar Sinatra syntax similar to that of defining routes for a controller.
 
 === Usage
 
-Let's take a look at using the MailerPlugin in an application. By default, MailerPlugin uses the built-in sendmail
-functionality on the server. However, smtp is also supported using the following configuration:
+Let's take a look at using the Mailer in an application. By default, the Mailer uses the built-in sendmail
+command on the server. However, smtp is also supported using the following configuration:
 
-    Padrino::Mailer::Base.smtp_settings = {
-      :host   => 'smtp.gmail.com',
-      :port   => '587',
-      :tls    => true,
-      :user   => 'user',
-      :pass   => 'pass',
-      :auth   => :plain
-   }
+  # Example for configuring gmail smtp
+  set :delivery_method, :smtp => {
+    :address              => "smtp.gmail.com",
+    :port                 => 587,
+    :domain               => 'your.host.name',
+    :user_name            => '<username>',
+    :password             => '<password>',
+    :authentication       => 'plain',
+    :enable_starttls_auto => true
+  }
 
-Once those have been defined, the default will become smtp delivery unless overwritten in an individual mail definition.
-Next, we should define a custom mailer extended from <tt>Padrino::Mailer::Base</tt>.
+Once the delivery settings have been defined, the default will become smtp delivery but can be overwritten in each message.
+
+Padrino supports sending quick emails (using either sendmail or smtp) right from your controllers.
+This is ideal for ‘one-off’ emails where the ‘full’ mailer declaration is simply unnecessary.
+
+Delivering an email from within your controller is simple:
+
+  # app/controllers/session.rb
+  post :create do
+    email(:to => "john@smith.com", :subject => "Successfully Registered!", :body => "Test Body")
+  end
+
+Padrino also supports structured mailer declarations. We can define a new mailer using a <tt>mailer</tt> block.
 
   # app/mailers/sample_mailer.rb
-  class SampleMailer < Padrino::Mailer::Base
-    def registration_email(name, user_email_address)
-      from 'admin@site.com'
-      to user_email_address
+  MyAppName.mailers :sample do
+    email :registration do |name|
+      from    'admin@site.com'
+      to      'user@domain.com'
       subject 'Welcome to the site!'
-      body    :name => name
-      type    'html'                # optional, defaults to plain/text
-      charset 'windows-1252'        # optional, defaults to utf-8
-      via     :sendmail             # optional, to smtp if defined otherwise sendmail
-      template 'sample_mailer/foo'  # optional, defaults to views/sample_mailer/registration_email.erb
+      locals  :name => name
+      content_type 'html'        # optional, defaults to plain/text
+      charset 'windows-1252'     # optional, defaults to utf-8
+      via     :sendmail          # optional, smtp if defined otherwise sendmail
+      render  'registration'
+    end
+  end
+
+In addition to a standard body, Padrino also easily supports multi-part emails:
+
+  # app/mailers/sample_mailer.rb
+  MyAppName.mailers :sample do
+    email :registration do |name|
+      to      'padrino@test.lindsaar.net'
+      subject "nested multipart"
+      from    "test@example.com"
+
+      text_part { render('multipart/basic.plain') }
+      html_part { render('multipart/basic.html')  }
     end
   end
 
-This defines a mail called '<tt>registration_mail</tt>' with the specified attributes for delivery. The <tt>body</tt> method
-is passing the <tt>name</tt> attribute to the body message template which should be defined in
-<tt>[views_path]/sample_mailer/registration_email.erb</tt> as shown below:
+Defaults can also be declared on a per-mailer or app-wide basis:
 
-  # ./views/sample_mailer/registration_email.erb
+  # app/app.rb
+  set :mailer_defaults, :from => 'admin@site.com'
+
+  # app/mailers/sample_mailer.rb
+  MyAppName.mailers :sample do
+    defaults :content_type => 'html'
+    email :registration do |name, age|
+      # Uses default 'content_type' and 'from' values but can also overwrite them
+      to      'user@domain.com'
+      subject 'Welcome to the site!'
+      locals  :name => name
+      render  'registration'
+    end
+  end
+
+This defines a message called '<tt>registration</tt>' with the specified attributes. The <tt>body</tt> method
+is invoking the render function passing the <tt>name</tt> attribute to the body message template which is defined in
+<tt>[views_path]/mailers/sample/registration.erb</tt> as shown below:
+
+  # ./views/mailers/sample/registration.erb
   This is the body of the email and can access the <%= name %> that was passed in from the mailer definition
   That's all there is to defining the body of the email which can be plain text or html
 
 Once the mailer definition has been completed and the template has been defined, the email can be sent using:
 
-  SampleMailer.deliver(:registration_email, "Bob", "bob@bobby.com")
-
-or if you like the method_missing approach:
-
-  SampleMailer.deliver_registration_email "Bob", 'bob@bobby.com'
+  deliver(:sample, :registration_email, "Bob", "21")
 
-And that will then deliver the email according the the configured options. This is really all you need to send emails.
+And that will then deliver the email according the the configured options. This is all you need to send basic emails.
 
-Be sure to check out the
+The mailer also supports the attachment of files and various other options. Be sure to check out the
 {Padrino Mailer}[http://www.padrinorb.com/guides/padrino-mailer] guide for more details on usage.
 
 == Copyright

data/Rakefile

@@ -1,53 +1,5 @@
-require 'rubygems'
-require 'rake'
-
-require File.expand_path("../../padrino-core/lib/padrino-core/version.rb", __FILE__)
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "padrino-mailer"
-    gem.summary = "Mailer system for padrino"
-    gem.description = "Mailer system for padrino allowing easy delivery of application emails"
-    gem.email = "padrinorb@gmail.com"
-    gem.homepage = "http://github.com/padrino/padrino-framework/tree/master/padrino-mailer"
-    gem.authors = ["Padrino Team", "Nathan Esquenazi", "Davide D'Agostino", "Arthur Chiu"]
-    gem.rubyforge_project = 'padrino-mailer'
-    gem.version = Padrino.version
-    gem.add_runtime_dependency     "padrino-core",  "= #{Padrino.version}"
-    gem.add_runtime_dependency     "tmail",         ">= 1.2"
-    gem.add_development_dependency "shoulda",       ">= 2.10.3"
-    gem.add_development_dependency "haml",          ">= 2.2.1"
-    gem.add_development_dependency "mocha",         ">= 0.9.7"
-    gem.add_development_dependency "rack-test",     ">= 0.5.0"
-    gem.add_development_dependency "webrat",        ">= 0.5.1"
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
-  Jeweler::GemcutterTasks.new
-  Jeweler::RubyforgeTasks.new { |r| r.doc_task = :none }
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
-end
+# coding:utf-8
+RAKE_ROOT = __FILE__
 
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-end
-
-begin
-  require 'rcov/rcovtask'
-  Rcov::RcovTask.new do |rcov|
-    rcov.libs << 'test'
-    rcov.pattern = 'test/**/test_*.rb'
-    rcov.verbose = true
-    rcov.rcov_opts << ['--exclude /Gems/1.8/gems/,padrino-core,padrino-cache,padrino-gen,padrino-helpers,padrino-admin']
-  end
-rescue LoadError
-  task :rcov do
-    abort "RCov is not available. In order to run rcov, you must: sudo gem install relevance-rcov"
-  end
-end
-
-task :default => :test
+require 'rubygems'
+require File.expand_path(File.dirname(__FILE__) + '/../gem_rake_helper')

data/lib/padrino-mailer.rb

@@ -4,23 +4,31 @@ begin
 rescue LoadError
   require 'sinatra/tilt'
 end
-require 'padrino-core/support_lite'
+require 'padrino-core/support_lite' unless defined?(SupportLite)
+require 'mail'
 
-Dir[File.dirname(__FILE__) + '/padrino-mailer/**/*.rb'].each { |file| require file }
+# Require respecting order of our dependencies
+FileSet.glob_require('padrino-mailer/**/*.rb', __FILE__)
 
 module Padrino
   ##
-  # This component uses an enhanced version of the excellent pony library (vendored) for a powerful but simple mailer
-  # system within Padrino (and Sinatra).
-  # There is full support for using an html content type as well as for file attachments.
+  # This component uses the 'mail' library to create a powerful but simple mailer system within Padrino (and Sinatra).
+  # There is full support for using plain or html content types as well as for attaching files.
   # The MailerPlugin has many similarities to ActionMailer but is much lighterweight and (arguably) easier to use.
   #
   module Mailer
     ##
-    # Used Padrino::Application for register Padrino::Mailer::Base::views_path
+    # Register
     #
-    def self.registered(app)
-      Padrino::Mailer::Base::views_path << app.views
+    #   Padrino::Mailer::Helpers
+    #
+    # for Padrino::Application
+    #
+    class << self
+      def registered(app)
+        app.helpers Padrino::Mailer::Helpers
+      end
+      alias :included :registered
     end
   end # Mailer
 end # Padrino

data/lib/padrino-mailer/base.rb

@@ -3,100 +3,79 @@ module Padrino
     ##
     # This is the abstract class that other mailers will inherit from in order to send mail
     #
-    # You can set the default delivery settings through:
+    # You can set the default delivery settings from your app through:
     #
-    #   Padrino::Mailer::Base.smtp_settings = {
-    #     :host   => 'smtp.yourserver.com',
-    #     :port   => '25',
-    #     :user   => 'user',
-    #     :pass   => 'pass',
-    #     :auth   => :plain # :plain, :login, :cram_md5, no auth by default
-    #     :domain => "localhost.localdomain" # the HELO domain provided by the client to the server
+    #   set :delivery_method, :smtp => {
+    #     :address         => 'smtp.yourserver.com',
+    #     :port            => '25',
+    #     :user_name       => 'user',
+    #     :password        => 'pass',
+    #     :authentication  => :plain # :plain, :login, :cram_md5, no auth by default
+    #     :domain          => "localhost.localdomain" # the HELO domain provided by the client to the server
     #   }
     #
+    # or sendmail:
+    #
+    #   set :delivery_method, :sendmail
+    #
+    # or for tests:
+    #
+    #   set :delivery_method, :test
+    #
     # and then all delivered mail will use these settings unless otherwise specified.
     #
     class Base
-      ##
-      # Returns the available mail fields when composing a message
-      #
-      def self.mail_fields
-        [:to, :cc, :bcc, :reply_to, :from, :subject, :content_type, :charset, :via, :attachments, :template]
-      end
-
-      @@views_path = []
-      cattr_accessor :smtp_settings
-      cattr_accessor :views_path
-      attr_accessor :mail_attributes
-
-      def initialize(mail_name=nil) #:nodoc:
-        @mail_name = mail_name
-        @mail_attributes = {}
-      end
-
-      ##
-      # Defines a method allowing mail attributes to be set into a hash for use when delivering
-      #
-      self.mail_fields.each do |field|
-        define_method(field) { |value| @mail_attributes[field] = value }
-      end
-
-      ##
-      # Assigns the body key to the mail attributes either with the rendered body from a template or the given string value
-      #
-      def body(body_value)
-        final_template = template_path
-        raise "Template for '#{@mail_name}' could not be located in views path!" unless final_template
-        @mail_attributes[:body] = Tilt.new(final_template).render(self, body_value.symbolize_keys) if body_value.is_a?(Hash)
-        @mail_attributes[:body] = body_value if body_value.is_a?(String)
-      end
+      attr_accessor :delivery_settings, :app, :mailer_name, :messages
 
-      ##
-      # Returns the path to the email template searched for using glob pattern
-      #
-      def template_path
-        self.views_path.each do |view_path|
-          template = Dir[File.join(view_path, template_pattern)].first
-          return template if template
-        end
+      def initialize(app, name, &block) #:nodoc:
+        @mailer_name = name
+        @messages    = {}
+        @defaults    = {}
+        @app         = app
+        instance_eval(&block)
       end
 
       ##
-      # Delivers the specified message for mail_name to the intended recipients
-      # mail_name corresponds to the name of a defined method within the mailer class
+      # Defines a mailer object allowing the definition of various email messages that can be delivered
       #
       # ==== Examples
       #
-      #   SampleMailer.deliver(:birthday_message)
-      #
-      def self.deliver(mail_name, *args)
-        mail_object = self.new(mail_name)
-        mail_object.method(mail_name).call(*args)
-        MailObject.new(mail_object.mail_attributes, self.smtp_settings).deliver
-      end
-
-      ##
-      # Returns true if a mail exists with the name being delivered
+      #   email :birthday do |name, age|
+      #     subject "Happy Birthday!"
+      #     to   'john@fake.com'
+      #     from 'noreply@birthday.com'
+      #     locals 'name' => name, 'age' => age
+      #     render 'birthday'
+      #   end
       #
-      def self.respond_to?(method_sym, include_private = false)
-        method_sym.to_s =~ /deliver_(.*)/ ? self.method_defined?($1) : super(method_sym, include_private)
+      def email(name, &block)
+        raise "The email '#{name}' is already defined" if self.messages[name].present?
+        self.messages[name] = Proc.new { |*attrs|
+          message = Mail::Message.new(self.app)
+          message.defaults = self.defaults if self.defaults.any?
+          message.delivery_method(*delivery_settings)
+          message.instance_exec(*attrs, &block)
+          message
+        }
       end
-
-      ##
-      # Handles method missing for a mailer class. Delivers a message based on the method
-      # being called i.e #deliver_birthday_message(22) invokes #birthday_message(22) to setup mail object
+      alias :message :email
+      
+      # Defines the default attributes for a message in this mailer (including app-wide defaults)
+      # 
+      # ==== Examples
       #
-      def self.method_missing(method_sym, *arguments, &block)
-        method_sym.to_s =~ /deliver_(.*)/ ? self.deliver($1, *arguments) : super(method_sym, *arguments, &block)
-      end
-
-      private
-
-        # Returns the glob pattern of the template file to locate and render
-        def template_pattern
-          @_pattern ||= (@mail_attributes[:template].present? ? "#{@mail_attributes[:template]}.*" :
-                         File.join(self.class.name.underscore.split("/").last, "#{@mail_name}.*"))
+      #   mailer :alternate do
+      #    defaults :from => 'padrino@from.com', :to => 'padrino@to.com'
+      #    email(:foo) do ... end
+      #  end
+      # 
+      def defaults(attributes=nil)
+        if attributes.nil? # Retrieve the default values
+          @app.respond_to?(:mailer_defaults) ? @app.mailer_defaults.merge(@defaults) : @defaults
+        else # updates the default values
+          @defaults = attributes
         end
+      end
     end # Base
   end # Mailer
-end # Padrino
+end # Padrino

data/lib/padrino-mailer/ext.rb

@@ -0,0 +1,231 @@
+module Mail
+  class Message
+    include Sinatra::Templates
+    include Padrino::Rendering if defined?(Padrino::Rendering)
+
+    def initialize_with_app(*args, &block)
+      @template_cache = Tilt::Cache.new
+      # Check if we have an app passed into initialize
+      if args[0].respond_to?(:views) && args[0].respond_to?(:reload_templates?)
+        app                       = args.shift
+        settings.views            = File.join(app.views, 'mailers')
+        settings.reload_templates = app.reload_templates?
+      else
+        # Set a default view for this class
+        settings.views = File.expand_path("./mailers")
+        settings.reload_templates = true
+      end
+
+      # Run the original initialize
+      initialize_without_app(*args, &block)
+    end
+    alias_method_chain :initialize, :app
+
+    ##
+    # Setup like in Sinatra/Padrino apps content_type and template lookup.
+    #
+    # ==== Examples
+    #
+    #   # This add a email plain part if a template called bar.plain.* is found
+    #   # and a html part if a template called bar.html.* is found
+    #   email do
+    #     from     'from@email.com'
+    #     to       'to@email.com'
+    #     subject  'Welcome here'
+    #     provides :plain, :html
+    #     render   "foo/bar"
+    #   end
+    #
+    def provides(*formats)
+      if formats.empty?
+        @_provides ||= []
+      else
+        @_provides = formats.flatten.compact
+      end
+    end
+
+    ##
+    # Helper to add a text part to a multipart/alternative email.  If this and
+    # html_part are both defined in a message, then it will be a multipart/alternative
+    # message and set itself that way.
+    #
+    # ==== Examples
+    #
+    #  text_part "Some text"
+    #  text_part { render('multipart/basic.text') }
+    #
+    def text_part(value=nil, &block)
+      if block_given? || value
+        @text_part = self.part(:content_type => "text/plain", :body => value, :part_block => block)
+        add_multipart_alternate_header unless html_part.blank?
+      else
+        @text_part || find_first_mime_type("text/plain")
+      end
+    end
+
+    ##
+    # Helper to add a html part to a multipart/alternative email.  If this and
+    # text_part are both defined in a message, then it will be a multipart/alternative
+    # message and set itself that way.
+    #
+    # ==== Examples
+    #
+    #  html_part "Some <b>Html</b> text"
+    #  html_part { render('multipart/basic.html') }
+    #
+    def html_part(value=nil, &block)
+      if block_given? || value
+        @html_part = self.part(:content_type => "text/html", :body => value, :part_block => block)
+        add_multipart_alternate_header unless text_part.blank?
+      else
+        @html_part || find_first_mime_type("text/html")
+      end
+    end
+
+    ##
+    # Allows you to add a part in block form to an existing mail message object
+    #
+    # ==== Examples
+    #
+    #  mail = Mail.new do
+    #    part :content_type => "multipart/alternative", :content_disposition => "inline" do |p|
+    #      p.part :content_type => "text/plain", :body => "test text\nline #2"
+    #      p.part :content_type => "text/html", :body => "<b>test</b> HTML<br/>\nline #2"
+    #    end
+    #  end
+    #
+    def part(params = {}, &block)
+      part_block = params.delete(:part_block)
+      new_part = Mail::Part.new(params)
+      new_part.settings.views = settings.views
+      new_part.settings.reload_templates = settings.reload_templates?
+      new_part.instance_eval(&part_block) if part_block
+      yield new_part if block_given?
+      add_part(new_part)
+    end
+
+    def do_delivery_with_logging
+      logger.debug "Sending email to: #{destinations.join(" ")}"
+      encoded.to_lf.split("\n").each { |line| logger << ("  " + line) } if logger.debug?
+      do_delivery_without_logging
+    end
+    alias_method_chain :do_delivery, :logging if Padrino.respond_to?(:logger)
+
+    ##
+    # Sinatra and Padrino compatibility
+    #
+    def settings
+      self.class
+    end
+    alias :options :settings
+
+    ##
+    # Sets the message defined template path to the given view path
+    #
+    def views(value)
+      settings.views = value
+    end
+
+    ##
+    # Sets the local variables available within the message template
+    #
+    def locals(value)
+      @_locals = value
+    end
+
+    ##
+    # Returns the templates for this message
+    #
+    def self.templates
+      @_templates ||= {}
+    end
+
+    ##
+    # Sets the message defined template path to the given view path
+    #
+    def self.views=(value)
+      @_views = value
+    end
+
+    ##
+    # Returns the template view path defined for this message
+    #
+    def self.views
+      @_views
+    end
+
+    ##
+    # Modify whether templates should be reloaded (for development)
+    #
+    def self.reload_templates=(value)
+      @_reload_templates = value
+    end
+
+    ##
+    # Returns true if the templates will be reloaded; false otherwise.
+    #
+    def self.reload_templates?
+      @_reload_templates
+    end
+
+    ##
+    # Return the path of this file, only for compatiblity with sinatra rendering methods
+    #
+    def self.caller_locations
+      [[File.dirname(__FILE__), 1]]
+    end
+
+    ##
+    # Modify the default attributes for this message (if not explicitly specified)
+    #
+    def defaults=(attributes)
+      @_defaults = attributes
+      @_defaults.each_pair { |k, v| default(k.to_sym, v) } if @_defaults.is_a?(Hash)
+    end
+
+    # Shortcut for delivery_method with smarter smtp overwrites
+    def via(method = nil, settings = {})
+      if method.nil?
+        delivery_method
+      elsif method.to_sym != :smtp
+        delivery_method(method, settings)
+      elsif method.to_sym == :smtp && (settings.any? || delivery_method.class.to_s !~ /smtp/i)
+        delivery_method(method, settings)
+      end
+    end
+
+    ##
+    # If the value is empty return a symbol that rappresent the content type so:
+    #
+    #   "text/plain" => :plain
+    #
+    # See Padrino::Mailer::Mime for more usage informations.
+    #
+    def content_type_with_symbol(value=nil)
+      value = Padrino::Mailer::Mime::MIME_TYPES.find { |k,v| v == value }[0] rescue value if value.is_a?(Symbol)
+      mime = content_type_without_symbol(value)
+      Padrino::Mailer::Mime.mime_type(mime)
+    end
+    alias_method_chain :content_type, :symbol
+
+    private
+
+      # Defines the render for the mailer utilizing the padrino 'rendering' module
+      def render(engine, data=nil, options={}, locals={}, &block)
+        locals = @_locals if options[:locals].blank? && locals.blank?
+        # Reload templates
+        @template_cache.clear if settings.reload_templates?
+        # Setup provides
+        provides.each do |format|
+          part do |p|
+            p.content_type(format)
+            p.send(:render, engine, data, options, locals, &block)
+            add_multipart_alternate_header unless html_part.blank?
+          end
+        end
+        # Setup the body if we don't have provides
+        self.body = super(engine, data, options, locals, &block) if provides.empty?
+      end
+
+  end # Message
+end # Mail