MJML + ERb/Haml/Slim view template
Ruby Logos
Pull request Compare This branch is 46 commits ahead of plataformatec:master.
Latest commit 7c9c625 Oct 25, 2016 @sighmon Merged in Mateusz's pull request that adds support for HAML and other…
… template languages by using a config initializer. Defaults to ERB.
Permalink
Failed to load latest commit information.
certs Signed gem for v2.1.1 release. May 30, 2016
gemfiles Add support for Rails 4.2, generate a mailer layout on 4.2 by default Dec 27, 2014
lib Merged in Mateusz's pull request that adds support for HAML and other… Oct 25, 2016
test add tests for working with alternate template_path Jun 20, 2016
.gitignore Updated license date. May 31, 2016
.travis.yml Updated to support MJML v3.x Oct 22, 2016
CHANGELOG.md Updated to work with MJML v2.x and also runs an MJML binary check and… Jun 9, 2016
Gemfile Updated the gem to work with MJML v2.1.1 May 27, 2016
Gemfile.lock Merged in Mateusz's pull request that adds support for HAML and other… Oct 25, 2016
Guardfile Added Guard, commented out by default. Edited the contact test to inc… May 20, 2016
MIT-LICENSE Updated license date. May 31, 2016
README.md Merged in Mateusz's pull request that adds support for HAML and other… Oct 25, 2016
Rakefile Added mjml parser. Next: fix tests. May 3, 2016
mjml-rails-2.1.1.gem Signed gem for v2.1.1 release. May 30, 2016
mjml-rails-2.1.1.gem.sha512 Signed gem for v2.1.1 release. May 30, 2016
mjml-rails-2.1.4.1.gem Cleaned up the gem install line removing the 'require'. Jun 8, 2016
mjml-rails-2.1.4.1.gem.sha512 Cleaned up the gem install line removing the 'require'. Jun 8, 2016
mjml-rails-2.1.4.gem Updated for MJML v2.1.4 Jun 2, 2016
mjml-rails-2.1.4.gem.sha512 Updated for MJML v2.1.4 Jun 2, 2016
mjml-rails-2.2.0.gem Updated to 2.2.0 Jun 9, 2016
mjml-rails-2.2.0.gem.sha512 Updated to 2.2.0 Jun 9, 2016
mjml-rails-2.3.0.gem Updated to support MJML v3.x Oct 22, 2016
mjml-rails-2.3.0.gem.sha512 Updated to support MJML v3.x Oct 22, 2016
mjml-rails-2.3.1.gem Merged Tyler Hunt's mime-type fix so that the mjml mime type is now r… Oct 24, 2016
mjml-rails-2.3.1.gem.sha512 Merged Tyler Hunt's mime-type fix so that the mjml mime type is now r… Oct 24, 2016
mjml-rails-2.4.0.gem Merged in Mateusz's pull request that adds support for HAML and other… Oct 25, 2016
mjml-rails-2.4.0.gem.sha512 Merged in Mateusz's pull request that adds support for HAML and other… Oct 25, 2016
mjml-rails.gemspec Added pix to the authors. Jun 9, 2016

README.md

MJML-Rails

Build Status Gem Version

MJML-Rails allows you to render HTML e-mails from an MJML template.

An example template might look like:

<!-- ./app/views/user_mailer/email.mjml -->
<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <mj-text>Hello World</mj-text>
          <%= render :partial => 'info', :formats => [:html] %>
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

And the partial _info.mjml:

<!-- ./app/views/user_mailer/_info.mjml -->
<mj-text>This is <%= @user.username %></mj-text>
  • Notice you can use ERb and partials inside the template.

Your user_mailer.rb might look like this::

# ./app/mailers/user_mailer.rb
class UserMailer < ActionMailer::Base
  def user_signup_confirmation()
    mail(to: 'test@example.com', subject: 'test') do |format|
      format.text
      format.mjml
    end
  end
end

Installation

Add it to your Gemfile.

gem 'mjml-rails'

Run the following command to install it:

bundle install

Install the MJML parser (optional -g to install it globally):

npm install -g mjml@^3.0

If you're using :haml or any other Rails template language, create an initializer to set it up:

# config/initializers/mjml.rb
Mjml.setup do |config|
  config.template_language = :erb # :erb (default), :slim, :haml, or any other you are using
end

MJML v3.x support

Version 2.3.0 of this gem brings support for MJML 3.x

If you'd rather still stick with MJML 2.x then lock the mjml-rails gem:

gem 'mjml-rails', '2.2.0'

How to guides

Hugo Giraudel wrote a post on using MJML in Rails.

Sending Devise user emails

If you use Devise for user authentication and want to send user emails with MJML templates, here's how to override the devise mailer:

# app/mailers/devise_mailer.rb
class DeviseMailer < Devise::Mailer
  def reset_password_instructions(record, token, opts={})
    @token = token
    @resource = record
    # Custom logic to send the email with MJML
    mail(
      template_path: 'devise/mailer',
      from: "some@email.com", 
      to: record.email, 
      subject: "Custom subject"
    ) do |format|
      format.mjml
      format.text
    end
  end
end

Now tell devise to user your mailer in config/initializers/devise.rb by setting config.mailer = 'DeviseMailer' or whatever name you called yours.

And then your MJML template goes here: app/views/devise/mailer/reset_password_instructions.mjml

Devise also have more instructions if you need them.

Deploying with Heroku

To deploy with Heroku you'll need to setup multiple buildpacks so that Heroku first builds Node for MJML and then the Ruby environment for your app.

Once you've installed the Heroku Toolbelt you can setup the buildpacks from the commandline:

$ heroku buildpacks:set heroku/ruby

And then add the Node buildpack to index 1 so it's run first:

$ heroku buildpacks:add --index 1 heroku/nodejs

Check that's all setup by running:

$ heroku buildpacks

Next you'll need to setup a package.json file in the root, something like this:

{
  "name": "your-site",
  "version": "1.0.0",
  "description": "Now with MJML email templates!",
  "main": "index.js",
  "directories": {
    "doc": "doc",
    "test": "test"
  },
  "dependencies": {
    "mjml": "^3.0"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/your-repo/your-site.git"
  },
  "keywords": [
    "mailer"
  ],
  "author": "Your Name",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/sighmon/mjml-rails/issues"
  },
  "homepage": "https://github.com/sighmon/mjml-rails"
}

Then $ git push heroku master and it should Just WorkTM.

Bug reports

If you discover any bugs, feel free to create an issue on GitHub. Please add as much information as possible to help us fixing the possible bug. We also encourage you to help even more by forking and sending us a pull request.

github.com/sighmon/mjml-rails/issues

Maintainers

License

MIT License. Copyright 2016 Simon Loffler. sighmon.com

Lovingly built on github.com/plataformatec/markerb