effective_email_templates 0.2.8

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 84fc52994b336f0edeb95c8e579b18059c940495
+  data.tar.gz: 3c6adf8992086a0209fc8c763296978e61b47d9e
+SHA512:
+  metadata.gz: 3256fb050c2c3e4162ecd4d6eabe69dec4f6731d338cd0746dcc3120bc3c197088e40fdc923ad38d4244ec59d910a0dffa569aad166956bc323a45c4c93adfdb
+  data.tar.gz: d9b1b88b614d46a12da2403a7a658693940cb85697bcf5ad6ac17ff80c07bc4a75f8d4797bf3582badb902f5b392005adab558c17683ce020a092ce0d8a517b7

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 Code and Effect Inc.
+
+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,195 @@
+# Effective Email Templates
+
+Description!!
+
+Rails 3.2.x and Rails 4 Support
+
+## Getting Started
+
+Add to your Gemfile:
+
+```ruby
+gem 'effective_email_templates', :git => 'https://github.com/code-and-effect/effective_email_templates'
+```
+
+Run the bundle command to install it:
+
+```console
+bundle install
+```
+
+Then run the generator:
+
+```ruby
+rails generate effective_email_templates:install
+```
+
+The generator will install an initializer which describes all configuration options and creates a database migration.
+
+If you want to tweak the table name (to use something other than the default 'email_templates'), manually adjust both the configuration file and the migration now.
+
+Then migrate the database:
+
+```ruby
+rake db:migrate
+```
+
+
+## Usage
+
+- Create some email templates at `/admin/email_templates`
+- Create a mailer method for each email
+  - Mailer objects need to inherit from `Effective::LiquidMailer`
+  - Mailer methods and email template slugs need to match up
+  - Email headers can be declared in the #mail method but can be overrided by the saved attributes on the Effective::EmailTemplate model.
+- Create mail objects and deliver them like normal
+
+An example liquid template (put these into the database through the admin panel: `/admin/email_templates`):
+
+```liquid
+Welcome to our site.  We think you're {{ adjective }}
+```
+
+The corresponding Mailer:
+
+```ruby
+# app/mailers/user_liquid_mailer.rb
+class UserLiquidMailer < Effective::LiquidMailer
+  def after_create_user(user)
+    @to_liquid = {
+      'adjective' => 'awesome'
+    }
+    mail(to: user.email)
+  end
+end
+```
+
+Send the emails like normal:
+
+```ruby
+mail = UserLiquidMailer.after_create_user(self)
+mail.deliver
+```
+
+### Default Templates
+
+Email templates can still be added by a developer into a view file if a rake task is run to import
+them into the database in production.  To create a view template for the `after_create_user` email
+above, simply create a template file inside /app/views (probably in the user_liquid directory)
+with a .liquid file extension.  That file should contain metadata in YAML format at the top
+surrounded by two lines with three hyphens:
+
+```yaml
+---
+subject: 'Hello User'                   # REQUIRED
+from: 'effective@email_templates.com'   # REQUIRED
+cc: 'my_friend@email_templates.com'     # optional
+bcc: 'my_secret_friend@example.com'     # optional
+---
+Hello new user! I'm a liquid template and you can use {{ }} inside of me to interpolate variables
+defined in the corresponding LiquidMailer method.
+```
+
+To add these templates to the database, run the `effective_email_templates:import_default_views` task.
+This task can be run even when no new templates have been added and will not overwrite existing
+database templates.  This allows you to run the rake task in a deploy script:
+
+```ruby
+# an example Heroku deploy script
+...
+system 'heroku run rake effective_email_templates:import_default_views'
+...
+```
+
+## Authorization
+
+All authorization checks are handled via the config.authorization_method found in the config/initializers/ file.
+
+It is intended for flow through to CanCan or Pundit, but that is not required.
+
+This method is called by all controller actions with the appropriate action and resource
+
+Action will be one of [:index, :show, :new, :create, :edit, :update, :destroy]
+
+Resource will the appropriate Effective::Something ActiveRecord object or class
+
+The authorization method is defined in the initializer file:
+
+```ruby
+# As a Proc (with CanCan)
+config.authorization_method = Proc.new { |controller, action, resource| authorize!(action, resource) }
+```
+
+```ruby
+# As a Custom Method
+config.authorization_method = :my_authorization_method
+```
+
+and then in your application_controller.rb:
+
+```ruby
+def my_authorization_method(action, resource)
+  current_user.is?(:admin) || EffectivePunditPolicy.new(current_user, resource).send('#{action}?')
+end
+```
+
+or disabled entirely:
+
+```ruby
+config.authorization_method = false
+```
+
+If the method or proc returns false (user is not authorized) an Effective::AccessDenied exception will be raised
+
+You can rescue from this exception by adding the following to your application_controller.rb:
+
+```ruby
+rescue_from Effective::AccessDenied do |exception|
+  respond_to do |format|
+    format.html { render 'static_pages/access_denied', :status => 403 }
+    format.any { render :text => 'Access Denied', :status => 403 }
+  end
+end
+```
+
+
+## License
+
+MIT License.  Copyright Code and Effect Inc. http://www.codeandeffect.com
+
+You are not granted rights or licenses to the trademarks of Code and Effect
+
+## TODO
+
+- minimize gem dependencies
+- remove unused non-admin routes and config option
+- Add an admin alert if there are mailer methods that do not have associated email templates
+- Show admin what the available arguments are for each template
+- remove `caller` usage from Effective::LiquidMailer (or remove requirement for Ruby 2.0+)
+- add `EffectiveEmailTemplates::present?` to check if a template model is present
+  - notify the app but don't raise an error if template is not present when an email is sent
+- configurable default from address
+- configurable prefix for subject line
+- use autoload rather than require
+- research panoramic gem's usage of the Resolver class and improve our Resolver usage
+- enable multipart emails
+- enable file attachments
+- import factories/fixtures in install task
+
+## Testing
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

data/Rakefile

@@ -0,0 +1,23 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+# Our tasks
+load 'lib/tasks/effective_email_templates/import_default_views.rake'
+
+# Testing tasks
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+
+task :default => :spec

data/app/assets/javascripts/effective_email_templates.js

@@ -0,0 +1 @@
+//= require_tree ./effective_email_templates

data/app/assets/stylesheets/effective_email_templates.css.scss

@@ -0,0 +1 @@
+//

data/app/controllers/admin/email_templates_controller.rb

@@ -0,0 +1,63 @@
+module Admin
+  class EmailTemplatesController < ApplicationController
+    before_filter :authenticate_user!   # This is devise, ensure we're logged in.
+
+    layout (EffectiveEmailTemplates.layout.kind_of?(Hash) ? EffectiveEmailTemplates.layout[:admin_email_templates] : EffectiveEmailTemplates.layout)
+
+    def index
+      EffectiveEmailTemplates.authorized?(self, :index, Effective::EmailTemplate)
+
+      @page_title = 'Manage Email Templates'
+      @datatable = Effective::Datatables::EmailTemplates.new() if defined?(EffectiveDatatables)
+      @page_title = 'Email Templates'
+    end
+
+    def new
+      @email_template = Effective::EmailTemplate.new
+      EffectiveEmailTemplates.authorized?(self, :new, @email_template)
+
+      @page_title = 'New Email Template'
+    end
+
+    def create
+      @email_template = Effective::EmailTemplate.new(email_template_params)
+      EffectiveEmailTemplates.authorized?(self, :create, @email_template)
+
+      if @email_template.save
+        flash[:success] = "Email template created successfully"
+        redirect_to effective_email_templates.admin_email_templates_path
+      else
+        flash.now[:error] = "Could not create email template"
+        @page_title = 'New Email Template'
+        render :new
+      end
+    end
+
+    def edit
+      @email_template = Effective::EmailTemplate.find(params[:id])
+      EffectiveEmailTemplates.authorized?(self, :edit, @email_template)
+
+      @page_title = 'Edit Email Template'
+    end
+
+    def update
+      @email_template = Effective::EmailTemplate.find(params[:id])
+      EffectiveEmailTemplates.authorized?(self, :update, @email_template)
+
+      if @email_template.update(email_template_params)
+        flash[:success] = "Email template updated successfully"
+        redirect_to effective_email_templates.admin_email_templates_path
+      else
+        flash.now[:error] = "Could not update email template"
+        @page_title = 'Edit Email Template'
+        render :edit
+      end
+    end
+
+    private
+
+    def email_template_params
+      params.require(:effective_email_template).permit([ :from, :cc, :bcc, :subject, :body ])
+    end
+  end
+end

data/app/errors/effective/access_denied.rb

@@ -0,0 +1,18 @@
+unless defined?(Effective::AccessDenied)
+  module Effective
+    class AccessDenied < StandardError
+      attr_reader :action, :subject
+
+      def initialize(message = nil, action = nil, subject = nil)
+        @message = message
+        @action = action
+        @subject = subject
+      end
+
+      def to_s
+        @message || I18n.t(:'unauthorized.default', :default => 'Access Denied')
+      end
+    end
+  end
+end
+

data/app/helpers/effective_email_templates_helper.rb

@@ -0,0 +1,19 @@
+module EffectiveEmailTemplatesHelper
+  def datatable_of(description_of_objects, datatable)
+    if datatable.nil?
+      content_tag(:p, "Please use Effective Datatables gem")
+    elsif datatable.collection.length > 0
+      render_datatable(datatable)
+    else
+      content_tag(:p, "There are no email templates")
+    end
+  end
+
+  def email_template_form_url( email_template )
+    if email_template.new_record?
+      effective_email_templates.admin_email_templates_path
+    else
+      effective_email_templates.admin_email_template_path( email_template )
+    end
+  end
+end

data/app/mailers/effective/email_template_mailer.rb

@@ -0,0 +1,14 @@
+module Effective
+  class EmailTemplateMailer < ActionMailer::Base
+    def templated_email(address, body, email_template, options)
+      @body = body
+      mail(
+        to: address,
+        from: email_template.from,
+        subject: email_template.subject,
+        cc: options.fetch(:cc, false),
+        bcc: options.fetch(:bcc, false),
+      )
+    end
+  end
+end

data/app/models/effective/datatables/email_templates.rb

@@ -0,0 +1,22 @@
+if defined?(EffectiveDatatables)
+  module Effective
+    module Datatables
+      class EmailTemplates < Effective::Datatable
+        default_order :subject, :asc
+
+        table_column :id, visible: false
+        table_column :slug
+        table_column :subject
+        table_column :from
+        table_column :cc, sortable: false, visible: false, label: 'CC'
+        table_column :bcc, sortable: false, visible: false, label: 'BCC'
+        table_column :body, sortable: false, visible: false
+        table_column :actions, sortable: false, partial: '/admin/email_templates/actions'
+
+        def collection
+          Effective::EmailTemplate.all
+        end
+      end
+    end
+  end
+end

data/app/models/effective/email_template.rb

@@ -0,0 +1,55 @@
+require 'liquid'
+Liquid::Template.error_mode = :strict # Raises a SyntaxError when invalid syntax is used
+
+module Effective
+  class EmailTemplate < ActiveRecord::Base
+
+    self.table_name = EffectiveEmailTemplates.email_templates_table_name.to_s
+
+    serialize :template, Liquid::Template
+
+    validate :slug_needs_to_have_simple_format
+    validates :slug,      presence: true, uniqueness: true
+    validates :body,      presence: true
+    validates :subject,   presence: true
+    validates :from,      presence: true
+    validates :template,  presence: true
+
+    before_validation :try_precompile
+
+    def precompile
+      begin
+        self.template = Liquid::Template.parse( body )
+      rescue Liquid::SyntaxError => error
+        errors.add :template, error.message
+      end
+    end
+
+    def mail_options
+      {
+        from: from,
+        subject: subject,
+        cc: cc,
+        bcc: bcc
+      }.delete_if { |_, v| v.blank? }
+    end
+
+    def render( *args )
+      template.render( *args )
+    end
+
+  private
+
+    def try_precompile
+      precompile if body_changed?
+    end
+
+    def slug_needs_to_have_simple_format
+      # convert slug to symbol
+      # add error if symbol has non-simple format (i.e. `:"symbol with spaces"` vs `:symbol_with_underscores`)
+      if /[@$"]/ =~ slug.to_sym.inspect || slug.match(/[A-Z]/)
+        errors.add(:slug, 'must have a simple format with no spaces, capital letters, and most punctuation (good: "hello_world", bad: "hello, world")')
+      end
+    end
+  end
+end