has_web_fallback 0.1.0

data/README

@@ -0,0 +1,43 @@
+HasWebFallback
+=============
+
+Extracts the common behaviour of wanting online versions of html emails.
+
+If a mailer function is described as has_web_fallback two things will happen.
+
+1.  The template will get access to an @web_fallback_url, a url (relative to /) to the web version of the email
+2.  After sending, if the email has an html part, that part will be written out to the public directory.
+
+Future Features
+===============
+Customizable urls/paths
+
+Installation
+============
+Right now, HasWebFallback requires UUIDTools to generate the names for the emails.
+config.gem 'uuidtools'
+
+
+Example
+=======
+
+class ExampleMailer < ActionMailer::Base
+
+	has_web_fallback :welcome, :keep_for=>7.days
+	has_web_fallback :goodbye, :keep_for=>10.minutes
+
+	def welcome
+		#
+	end
+
+	def goodbye
+		#
+	end
+end 
+
+... and in the template
+
+<%= link_to("View this email online", @web_fallback_url, :path_only=>false) %>
+
+
+Copyright (c) 2009 Gavin Montague, released under the MIT license

data/lib/has_web_fallback.rb

@@ -0,0 +1 @@
+require "leftbrained/has_web_fallback"

data/lib/leftbrained/has_web_fallback.rb

@@ -0,0 +1,139 @@
+require 'find'
+require 'ftools'
+require 'uuidtools'
+
+module Leftbrained
+    
+  module HasWebFallback #:nodoc:
+
+    WEB_FALLBACK_PATH = File.join(File.expand_path(RAILS_ROOT), "public")
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+      
+    # mattr_accessor :write_web_fallbacks
+    
+    module ClassMethods
+      
+      def has_web_fallback(name, options={})      
+        write_inheritable_attribute(:methods_with_web_fallback, {}) if methods_with_web_fallback.nil?
+        methods_with_web_fallback[name] = { :keep_for=>7.days }.merge(options)
+
+        class_eval <<-EOV
+        include Leftbrained::HasWebFallback::InstanceMethods
+        EOV
+      end
+      
+      def has_web_fallback?(method_name)
+        methods_with_web_fallback.include? method_name.to_sym
+      end
+            
+      def web_fallback_uuid_for(method_name)
+        UUIDTools::UUID.random_create.to_s<<".html"
+      end
+      
+      def methods_with_web_fallback
+        read_inheritable_attribute(:methods_with_web_fallback)
+      end
+      
+      def cache_deadline_for_web_fallback(method_name)
+        Time.now - cache_period_for_method_with_web_fallback(method_name)
+      end
+      
+      def clear_web_fallback_caches
+        methods_with_web_fallback.keys.each do |meth_name|
+          clear_web_fallback_cache meth_name
+        end
+      end
+      
+      def clear_web_fallback_cache(method_name)
+        web_fallback_caches_to_be_cleared(method_name).each do |file|
+          File.unlink(file)
+        end
+      end
+      
+      def web_fallback_caches_to_be_cleared(method_name)
+        return [] unless has_web_fallback? method_name
+        cut_off_time = cache_deadline_for_web_fallback(method_name)
+        path = path_for_web_fallback(method_name)
+        deletable = []
+        if File.exists? path
+          Find.find(path) do |path|
+            deletable << path if (File.mtime(path) <= cut_off_time) && File.file?(path)
+          end
+        end
+        deletable
+      end
+      
+      def cache_period_for_method_with_web_fallback(method_name)
+        methods_with_web_fallback[method_name.to_sym][:keep_for]      
+      end
+      
+      def url_for_web_fallback(method_name)
+        "/system/web_fallback/#{self.to_s.underscore.gsub("_mailer", '')}/#{method_name}"
+      end
+      
+      def path_for_web_fallback(method_name)
+        File.join(WEB_FALLBACK_PATH, url_for_web_fallback(method_name))
+      end
+                            
+    end # ClassMethods
+
+    module InstanceMethods      
+      
+      def web_fallback_uuid
+        @web_fallback_uuid ||= self.class.web_fallback_uuid_for(@action_name)
+      end
+      
+      def web_fallback_url
+        File.join(self.class.url_for_web_fallback(@action_name), web_fallback_uuid)
+      end
+      
+      def web_fallback_path
+        File.join(self.class.path_for_web_fallback(@action_name), web_fallback_uuid)
+      end
+      
+      def has_web_fallback?
+        self.class.has_web_fallback? @action_name
+      end
+      
+      # If this method needs a fallback version set an instance variable in the template
+      # so we can actually tell the user what the URL will be.
+      def render_message(method_name, body)
+        body[:web_fallback_url] = web_fallback_url if has_web_fallback?
+        super
+      end
+      
+      def write_web_fallback
+        return unless has_html_part?
+        FileUtils.mkdir_p(File.dirname(web_fallback_path))
+        f = File.new(web_fallback_path, 'w')
+        f.puts(html_part)
+        f.close
+      end
+      
+      def has_html_part?
+        !!mail.parts.find{ |part| 'text/html' == part.content_type }
+      end
+      
+      def html_part
+        mail.parts.find{ |part| 'text/html' == part.content_type }.body
+      end
+      
+      
+      # After delivering any mail, pop a version out to the file system
+      def deliver!(mail=@mail)
+        super(mail)
+        write_web_fallback if has_web_fallback?
+        mail
+      end
+      
+    end # InstanceMethods
+      
+  end
+  
+end
+
+ActionMailer::Base.class_eval { include Leftbrained::HasWebFallback }

data/test/has_web_fallback_test.rb

@@ -0,0 +1,124 @@
+require 'test_helper'
+
+
+require "#{File.dirname(__FILE__)}/test_helper"
+
+class HasWebFallbackTest < ActionMailer::TestCase
+  
+  class ExampleMailer < ActionMailer::Base
+    has_web_fallback :welcome
+    has_web_fallback :goodbye
+    
+    def welcome
+      recipients "no-one@example.com"
+      body[:name] = "Joe"
+      subject "welcome"
+    end
+    
+    def goodbye
+      body[:name] = "Joe"
+      subject "goodbye"
+    end
+    
+    def recover_password
+    end
+  end
+  # 
+
+  context "When included, ExampleMailer" do
+    
+    should "have a class attribute for tracking methods with fallbacks" do 
+      assert ExampleMailer.inheritable_attributes.include? :methods_with_web_fallback
+    end
+    
+    should "be able to identify if a method has a web fallback" do
+      assert ExampleMailer.has_web_fallback?(:welcome)
+      assert ExampleMailer.has_web_fallback?(:goodbye)
+    end
+    
+    should "be able to identify a method without a web fallback" do
+      assert !ExampleMailer.has_web_fallback?(:recover_password)
+    end
+    
+    should "be able to generate UUIDs" do # I know this is a lousy test, but how the hell would one test a UUID?
+      uuid_1 = ExampleMailer.web_fallback_uuid_for(:welcome)
+      uuid_2 = ExampleMailer.web_fallback_uuid_for(:welcome)
+      assert uuid_1 != uuid_2, "UUID clash - #{uuid_1} vs #{uuid_2}"
+    end
+  
+    should_eventually "be able to list cached files for a given function that should be deleted" do
+      # I have quite literally no idea how to test this without 
+      # mocking the living shit out File, or writing out to the file system.
+    end
+    
+  end
+  
+  context "A method with no fallback" do
+    setup do 
+      @recover_password_mail = ExampleMailer.send(:new, 'recover_password')  
+    end
+
+    should "know it doesn't have a fallback" do  
+      assert !@recover_password_mail.has_web_fallback?
+    end
+    
+    should "not write out an html version" do
+      @recover_password_mail.deliver!
+      assert !File.exists?(@recover_password_mail.web_fallback_path)
+    end
+  end
+
+  context "A method with fallback" do
+    setup do 
+      @welcome_mail = ExampleMailer.send(:new, 'welcome')
+    end
+
+    should "know if it has a web fallback " do 
+      assert @welcome_mail.has_web_fallback?
+    end
+    
+    context "and an html part" do
+      should "have a url to the email " do
+        assert_match /^\/system\/web_fallback\/has_web_fallback_test\/example\/welcome\/[a-z0-9\-]+\.html$/, @welcome_mail.web_fallback_url
+      end
+    
+      should "have an absolute_path to the file's location" do
+        assert @welcome_mail.web_fallback_path
+      end
+      
+      should "know it has an html part" do
+         assert @welcome_mail.has_html_part?
+       end
+    
+      should "be able to include a link in any of the body parts." do
+         @welcome_mail.parts.each do |part|
+          assert_match @welcome_mail.web_fallback_url, part.body
+         end
+      end
+      
+      should "write out an html version" do
+        @welcome_mail.deliver!
+        assert File.exists?(@welcome_mail.web_fallback_path)
+      end
+    end
+    
+    context "but no html part" do
+      setup do 
+        @goodbye_mail = ExampleMailer.send(:new, 'goodbye')
+      end
+      
+      should "know it doesn't have an html part" do
+        assert !@goodbye_mail.has_html_part?
+      end
+      
+      should "not write out an html version" do
+        @goodbye_mail.deliver!
+        assert !File.exists?(@goodbye_mail.web_fallback_path)
+      end
+            
+    end
+    
+  end
+  
+end
+

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+require 'stringio'
+require 'test/unit'
+require File.dirname(__FILE__) + '/../lib/has_web_fallback'
+
+# Reset out template path for AM to work with tests, apologies to any one else running tests....
+ActionMailer::Base.template_root = File.join(File.dirname(__FILE__), 'app', 'views')

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification 
+name: has_web_fallback
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Gavin Montague
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-22 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: actionmailer
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: uuidtools
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Adds the commonly required behaviour of caching web accessible versions of HTML emails to ActionMailer
+email: gavin@leftbrained.co.uk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/has_web_fallback.rb
+- lib/leftbrained/has_web_fallback.rb
+- README
+has_rdoc: true
+homepage: http://github.com/Govan/has_web_fallback
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Adds the commonly required behaviour of caching web accessible versions of HTML emails to ActionMailer
+test_files: 
+- test/has_web_fallback_test.rb
+- test/test_helper.rb