Effective Email Templates

Create email templates that an admin can edit and then send.

Rails 3.2.x through Rails 6

effective_email_templates 1.0

This is the 1.0 series of effective_email_templates.

This requires Twitter Bootstrap 4.

Please check out Effective Email Templates 0.x for more information using this gem with Bootstrap 3.

Getting Started

Add to your Gemfile:

gem 'haml-rails' # or try using gem 'hamlit-rails'
gem 'effective_email_templates'

Run the bundle command to install it:

bundle install

Then run the generator:

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:

rake db:migrate

And import the provided welcome email template:

rake effective_email_templates:import

Admin View

To manage the content of the email templates, navigate to /admin/email_templates or add,

link_to 'Email Templates', effective_email_templates.admin_email_templates_path to your menu.

Create Email Templates

The installer already created an app/mailers/email_templates_mailer.rb. You can change this name. And additional mailers can be created, just make sure they extend from Effective::EmailTemplatesMailer.

To create an email template:

Create a method inside the mailer, like def welcome. The @assigns instance variable should contain all the variables that are passed to the liquid view. Any variables that end in _url like root_url will be automatically expanded.

# app/mailers/email_templates_mailer.rb
class EmailTemplatesMailer < Effective::EmailTemplatesMailer
  def welcome(user)
    @assigns = {
      user: {
        first_name: user.first_name,
        last_name: user.last_name
      }
      adjective: 'awesome'
    }

    mail(to: user.email)
  end
end

Create a .liquid file in app/views/email_templates_mailer/welcome.liquid.

---
subject: 'Welcome {{ user.first_name }}'  # REQUIRED
from: '[email protected]'               # REQUIRED
cc: '[email protected]'                  # optional
bcc: '[email protected]'                 # optional
---
Welcome {{ user.first_name }} {{ user.last_name }}!

I am a liquid template that is imported to the database, and is then editable.

Thanks for using our site at {{ root_url }}.

Run rake effective_email_templates:import or rake effective_email_templates:overwrite

Remember to do this in your staging and production environments as well!
The import 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 if you are adding new templates frequently.

Send the emails like normal:

EmailTemplatesMailer.welcome(user).deliver

Authorization

All authorization checks are handled via the config.authorization_method found in the app/config/initializers/effective_email_templates.rb file.

It is intended for flow through to CanCan or Pundit, but neither of those gems are 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::EmailTemplate object or class

The authorization method is defined in the initializer file:

# As a Proc (with CanCan)
config.authorization_method = Proc.new { |controller, action, resource| authorize!(action, resource) }

# As a Custom Method
config.authorization_method = :my_authorization_method

and then in your application_controller.rb:

def my_authorization_method(action, resource)
  current_user.is?(:admin) || EffectivePunditPolicy.new(current_user, resource).send('#{action}?')
end

or disabled entirely:

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:

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

Permissions

To allow a user to see the admin area, using CanCan:

can :manage, Effective::EmailTemplate
can :admin, :effective_email_templates

License

MIT License. Copyright Code and Effect Inc.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Bonus points for test coverage
Create new Pull Request