idlemailer 1.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 347bc7e19b8427031ed9246730a710ca7ad8893f
-  data.tar.gz: 4e44c6a7525787ab0576655f863fa31b5d1359ff
+SHA256:
+  metadata.gz: 288e28b5d6f7ac40873806faa8bf56b8e66143a96819be6025238bcbc5fbc239
+  data.tar.gz: 76389af5d9027c264ae2cd2ae0f014a184a3bff41204a001d0a9061ef83e223f
 SHA512:
-  metadata.gz: 707144b2594688f8b838dc2eb3aa35f553c2f9bc188a0be8f6f812ccc7e801005a1068691ca8cf54d699564037e4a5fe0bb0f8e4c491425915dedc3e2ae8ef28
-  data.tar.gz: a349486802b1245cf60dd885b85dfbbb74ea266ee077a0ff0f1b366d864fb2004fd7718ecac63d674ce2bf667d8c2f64dced20935c78aae4f9371fd8a1f931e2
+  metadata.gz: 294f547d16812a33f260ac1dfd10602de80e62cda27c8bf6d4401745c2b8e75c74fd840103f2bb04552df1bc4da4da6878de8a4bd40ad213301171ba6649c8aa
+  data.tar.gz: f86dfb20178f2dbc43826b6ffb1e879009eed952be403be29f41873c2d19d7aa431e2e00b90ae6d1a8ebc58bd2d92a1637c054be7d4fe6f323fdb0443c47a480

data/README.md

@@ -1,15 +1,18 @@
 # IdleMailer
 
-A lightweight (~100 line) alternative to ActionMailer for hipsters who use Ruby but not Rails. Powered by [mail](http://www.rubydoc.info/gems/mail). Great for API-only backends that need to send email.
+A lightweight (~200 line) alternative to ActionMailer for Rubyists who are too cool for Rails. Powered by the [mail](http://www.rubydoc.info/gems/mail) gem. Great for API-only backends that need to send email.
 
 ## Installation
 
-    $ [sudo] gem install idlemailer
-    # Or add "idlemailer" to your Gemfile
+Add to your Gemfile.
+
+```ruby
+gem 'idlemailer'
+```
 
 ## Use
 
-IdleMailer is all about providing mailer classes and templates. But [the mail gem](http://www.rubydoc.info/gems/mail) has a great API, so you have unfettered access to it in your mailers through the "mail" object.
+IdleMailer provides mailer classes and templates on top of the [mail](http://www.rubydoc.info/gems/mail) gem. `mail` has a great API, so you have unfettered access to it in your mailers.
 
 ```ruby
 # Define your mailer class
@@ -17,18 +20,58 @@ class WidgetMailer
   include IdleMailer::Mailer
 
   def initialize(user, widget)
+    @widget = widget
     mail.to = user.email
     mail.subject = "Widget #{widget.sku}"
-    @widget = widget
+    # 'mail' is just a Mail object from the mail gem, so you can use the
+    # full Mail api here, e.g. to, subject, attachments, etc.
   end
 end
 
-# Create widget.html.erb and/or widget.text.erb templates.
-# They'll have access to instance variables like @widget above.
+# Create widget.html.erb and/or widget.text.erb in your templates directory.
+# They'll have access to instance variables like @widget above, as well as any methods you define.
 
 # Send your mail
-mailer = WidgetMailer.new(current_user, widget)
-mailer.deliver
+WidgetMailer.new(current_user, widget).deliver
+```
+
+### HTML escaping
+
+All values will be automatically HTML-escaped. If you need to bypass escapeing, use the `raw` helper:
+
+```ruby
+<%= raw @something_with_safe_html %>
+```
+
+### Inline templates
+
+If you prefer, you can embed your ERB templates right inside your Ruby class, instead of making separate template files. Slick amiright?
+
+```ruby
+class WidgetMailer
+  include IdleMailer::Mailer
+
+  # optionally override the default layout
+  self.layout = "widget_layout"
+
+  def initialize(user, widget)
+    @widget = widget
+    mail.to = user.email
+    mail.subject = "Widget #{widget.sku}"
+  end
+
+  text %(
+A new widget called <%= @widget %> was just created!
+
+Thanks!
+  )
+
+  html %(
+<p>A new widget called <%= @widget %> was just created!</p>
+
+<p>Thanks!</p>
+  )
+end
 ```
 
 ## Configure
@@ -40,7 +83,10 @@ IdleMailer.config do |config|
   # Directory containing the mailer templates
   config.templates = Pathname.new(Dir.getwd).join('templates')
 
-  # Name of the layout template. Here, the file(s) would be named
+  # Pre-cache all templates and layouts (instead of re-loading them on each delivery)
+  config.cache_templates = true
+
+  # Name of the default layout template. Here, the file(s) would be named
   # mailer_layout.html.erb and/or mailer_layout.text.erb.
   config.layout = 'mailer_layout'
 
@@ -73,7 +119,7 @@ end
 
 ## Testing
 
-Put the mailer in testing mode:
+Put the mailer into testing mode:
 
 ```ruby
 IdleMailer.config do |config|
@@ -81,10 +127,44 @@ IdleMailer.config do |config|
 end
 ```
 
-Then use mail gem's built in testing helpers in your specs:
+Then configure your test runner. Here's an example with RSpec:
+
+```ruby
+RSpec.configure do |config|
+  # Clear sent mail after every test
+  config.after :each do
+    IdleMailer::Testing.clear_mail!
+  end
+
+  # Include the test helpers in your specs
+  config.include IdleMailer::Testing::Helpers
+end
+```
+
+Your tests will have access to these helper methods. (Note you can also call them directly on `IdleMailer::Testing` as well)
 
 ```ruby
-sent = Mail::TestMailer.deliveries.any? { |mail| mail.to.include? @user.email }
+# quick boolean checks
+sent_mail_to? 'user@example.com'
+sent_mail_to? 'user@example.com', /subject/
+sent_mail_to? 'user@example.com', /subject/, /body/
+sent_mail_with_subject? /Foo/
+sent_mail_with_body? /Bar/
+sent_mail_from? 'user@example.com'
+
+# get arrays of matching sent mail (Mail::Message objects)
+mail_to 'user@example.com'
+mail_to 'user@example.com', /subject/
+mail_to 'user@example.com', /subject/, /body/
+mail_with_subject /Foo/
+mail_with_body /Bar/
+mail_from 'user@example.com'
+
+# get an array of all sent mail
+sent_mail
+
+# clear all sent mail
+clear_mail!
 ```
 
 ## License

data/lib/idlemailer/config.rb

@@ -1,13 +1,13 @@
 module IdleMailer
   # Struct for holding IdleMailer config
   #   templates A Pathname object pointing to the mail templates directory (defaults to ./templates)
-  #   layout Name of layout file, minus extention (defaults to mailer_layout)
+  #   layout Name of default layout file, minus extention (defaults to mailer_layout)
   #   delivery_method Symbol like :smtp or :test (see the mail gem for all options)
   #   delivery_options Hash of delivery options (see the mail gem for all options)
   #   default_from Default "from" address if it's left blank
   #   logger a Logger object for logging email
   #   log_body if true, the entire message body will be logged (instead of just the headers) (default false)
-  Config = Struct.new(:templates, :layout, :delivery_method, :delivery_options, :default_from, :logger, :log_body)
+  Config = Struct.new(:templates, :layout, :cache_templates, :delivery_method, :delivery_options, :default_from, :logger, :log_body)
   @config = Config.new
 
   # Takes a block and hands it an IdleMailer::Config object

data/lib/idlemailer/defaults.rb

@@ -1,6 +1,7 @@
 IdleMailer.config do |config|
   config.templates = Pathname.new(Dir.getwd).join('templates')
   config.layout = 'mailer_layout'
+  config.cache_templates = true
   config.delivery_method = :smtp
   config.delivery_options = {
     user_name: ENV['MAIL_USER'],

data/lib/idlemailer/html_safe_string.rb

@@ -0,0 +1,16 @@
+module IdleMailer
+  class HtmlSafeString < String
+    def <<(str)
+      safe_str = str.is_a?(HtmlSafeString) ? str : ERB::Util.html_escape(str.to_s)
+      super safe_str
+    end
+
+    def safe_concat(val)
+      self << HtmlSafeString.new(val)
+    end
+
+    def to_s
+      self
+    end
+  end
+end

data/lib/idlemailer/mailer.rb

@@ -4,6 +4,9 @@ module IdleMailer
   #  class WidgetMailer
   #    include IdleMailer::Mailer
   #
+  #    # optionally override the default layout
+  #    self.layout = "widget_layout"
+  #
   #    def initialize(address, widget)
   #      mail.to = address
   #      mail.subject = "Widget #{widget.sku}"
@@ -18,6 +21,10 @@ module IdleMailer
   #  mailer.deliver
   #
   module Mailer
+    def self.included(klass)
+      klass.extend TemplateManager
+    end
+
     # Deliver mail
     def deliver
       mailer = IdleMailer::Message.new(mail, self)

data/lib/idlemailer/message.rb

@@ -13,17 +13,19 @@ module IdleMailer
 
     # Deliver mail
     def deliver!
-      if has_template? 'html'
+      if mailer.class.has_template? 'html'
         html_body = layout('html') { body('html') }
         mail.html_part do
           content_type 'text/html; charset=UTF-8'
           body html_body
         end
       end
-      if has_template? 'text'
+
+      if mailer.class.has_template? 'text'
         text_body = layout('text') { body('text') }
         mail.text_part { body text_body }
       end
+
       config = IdleMailer.config
       mail.from config.default_from if mail.from.nil?
       mail.delivery_method config.delivery_method, config.delivery_options
@@ -35,35 +37,15 @@ module IdleMailer
     private
 
     def body(type)
-      render template_path(template_name, type)
+      render mailer.class.template(type)
     end
 
     def layout(type)
-      has_layout?(type) ? render(template_path(IdleMailer.config.layout, type)) { yield } : yield
-    end
-
-    def render(path)
-      mailer.render(ERB.new(File.read(path))) { yield }
-    end
-
-    def has_template?(type)
-      File.exists? template_path(template_name, type)
-    end
-
-    def has_layout?(type)
-      File.exists? template_path(IdleMailer.config.layout, type)
-    end
-
-    def template_name
-      @name ||= mailer.class.name.
-        gsub(/::/, File::SEPARATOR).
-        sub(/Mailer$/, '').
-        gsub(/([a-z])([A-Z])/, "\\1_\\2").
-        downcase
+      mailer.class.has_layout?(type) ? render(mailer.class.layout(type)) { yield } : yield
     end
 
-    def template_path(name, type)
-      IdleMailer.config.templates.join("#{name}.#{type}.erb")
+    def render(template)
+      mailer.render(template) { yield }
     end
   end
 end

data/lib/idlemailer/template_manager.rb

@@ -0,0 +1,68 @@
+module IdleMailer
+  # Loads a mailer's templates and layouts
+  module TemplateManager
+    def self.extended(klass)
+      klass.class_eval do
+        include Templates::Helpers
+        class << self
+          attr_reader :layouts, :templates
+        end
+        @custom_layout, @layouts, @templates = nil, {}, {}
+      end
+      klass.cache_templates! if IdleMailer.config.cache_templates
+    end
+
+    def text(str)
+      templates['text'] = Templates.compile str.chomp
+    end
+
+    def html(str)
+      templates['html'] = Templates.compile str.chomp
+    end
+
+    def template(type)
+      templates[type] || Templates.compile(template_path(template_name, type).read.chomp)
+    end
+
+    def layout(type)
+      layouts[type] || Templates.compile(template_path(layout_name, type).read.chomp)
+    end
+
+    def layout=(new_name)
+      @custom_layout = new_name
+      layouts.clear
+      cache_templates! if IdleMailer.config.cache_templates
+    end
+
+    def has_template?(type)
+      templates.has_key?(type) || template_path(template_name, type).exist?
+    end
+
+    def has_layout?(type)
+      layouts.has_key?(type) || template_path(layout_name, type).exist?
+    end
+
+    def template_name
+      @name ||= self.name.
+        gsub(/::/, File::SEPARATOR).
+        sub(/Mailer$/, '').
+        gsub(/([a-z])([A-Z])/, "\\1_\\2").
+        downcase
+    end
+
+    def layout_name
+      @custom_layout || IdleMailer.config.layout
+    end
+
+    def template_path(name, type)
+      IdleMailer.config.templates.join("#{name}.#{type}.erb")
+    end
+
+    def cache_templates!
+      layouts['text'] ||= layout 'text' if has_layout? 'text'
+      layouts['html'] ||= layout 'html' if has_layout? 'html'
+      templates['text'] ||= template 'text' if has_template? 'text'
+      templates['html'] ||= template 'html' if has_template? 'html'
+    end
+  end
+end

data/lib/idlemailer/templates.rb

@@ -0,0 +1,27 @@
+module IdleMailer
+  module Templates
+    def self.compile(src)
+      compiler = ERB::Compiler.new("<>")
+      compiler.pre_cmd = ["_erbout=+HtmlSafeString.new"]
+      compiler.put_cmd = "_erbout.safe_concat"
+      compiler.insert_cmd = "_erbout.<<"
+      compiler.post_cmd = ["_erbout"]
+      code, _enc = compiler.compile(src)
+      Template.new code.freeze
+    end
+
+    Template = Struct.new(:code) do
+      def result(bind)
+        _erbout = HtmlSafeString.new
+        eval code, bind
+      end
+    end
+
+    module Helpers
+      # Don't HTML-escape the given value
+      def raw(str)
+        HtmlSafeString.new(str)
+      end
+    end
+  end
+end

data/lib/idlemailer/testing.rb

@@ -0,0 +1,60 @@
+module IdleMailer
+  # Module for testing. You can call all IdleMailer::Testing::Helpers methods directly on this module if you want.
+  module Testing
+    # Helpers for your tests
+    module Helpers
+      # Returns true if any mail was sent from the given email address.
+      def sent_mail_from?(addr)
+        mail_from(addr).any?
+      end
+
+      # Returns true if any mail was sent to the given email address. You may pass subject and body patterns to get more specific (String or Regexp).
+      def sent_mail_to?(addr, subject = nil, body = nil)
+        mail_to(addr, subject, body).any?
+      end
+
+      # Returns true if any mail was sent matching the given subject (String or Regexp).
+      def sent_mail_with_subject?(pattern)
+        mail_with_subject(pattern).any?
+      end
+
+      # Returns true if any mail was sent matching the given body (Regexp).
+      def sent_mail_with_body?(pattern)
+        mail_with_body(pattern).any?
+      end
+
+      # Returns all mail sent from the given email address.
+      def mail_from(addr)
+        sent_mail.select { |m| m.from.include? addr }
+      end
+
+      # Returns all mail sent to the given email address. You may pass subject and body patterns to get more specific (String or Regexp).
+      def mail_to(addr, subject = nil, body = nil)
+        sent_mail.select { |m|
+          m.to.include?(addr) && (subject.nil? || subject === m.subject) && (body.nil? || body === m.to_s)
+        }
+      end
+
+      # Returns all mail sent matching the given subject (String or Regexp).
+      def mail_with_subject(pattern)
+        sent_mail.select { |m| pattern === m.subject }
+      end
+
+      # Returns all mail sent matching the given body (Regexp).
+      def mail_with_body(pattern)
+        sent_mail.select { |m| pattern === m.to_s }
+      end
+
+      # Returns all sent mail.
+      def sent_mail
+        Mail::TestMailer.deliveries
+      end
+
+      # Clears sent mail.
+      def clear_mail!
+        Mail::TestMailer.deliveries.clear
+      end
+    end
+    extend Helpers
+  end
+end

data/lib/idlemailer/version.rb

@@ -1,5 +1,5 @@
 # IdleMailer module
 module IdleMailer
   # Version number
-  VERSION = '1.0.0'
+  VERSION = '2.2.0'
 end

data/lib/idlemailer.rb

@@ -1,8 +1,16 @@
 require 'erb'
 require 'pathname'
 require 'mail'
+
 require 'idlemailer/config'
 require 'idlemailer/defaults'
 require 'idlemailer/message'
 require 'idlemailer/mailer'
+require 'idlemailer/template_manager'
+require 'idlemailer/templates'
+require 'idlemailer/html_safe_string'
 require 'idlemailer/version'
+
+module IdleMailer
+  autoload :Testing, 'idlemailer/testing'
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: idlemailer
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-03 00:00:00.000000000 Z
+date: 2021-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mail
@@ -36,8 +36,12 @@ files:
 - lib/idlemailer.rb
 - lib/idlemailer/config.rb
 - lib/idlemailer/defaults.rb
+- lib/idlemailer/html_safe_string.rb
 - lib/idlemailer/mailer.rb
 - lib/idlemailer/message.rb
+- lib/idlemailer/template_manager.rb
+- lib/idlemailer/templates.rb
+- lib/idlemailer/testing.rb
 - lib/idlemailer/version.rb
 homepage: https://github.com/jhollinger/idlemailer
 licenses: []
@@ -50,17 +54,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: A lightweight alternative to ActionMailer
 test_files: []
-has_rdoc: