alekseyg / mjml-ruby

✉️ MJML parser and template engine for Ruby

MJML Ruby

[!] REQUIRE NODEJS

MJML parser and template engine for Ruby. Allows to create email templates without mess.

Install

Add to Gemfile:

gem 'mjml-ruby', '~> 0.3.0', require: 'mjml'

or

$ gem install mjml-ruby

Install NodeJS and MJML (both installations will works local and global).

$ npm install -g mjml@^3.0.0
$ bundle install

Usage

MJML v3

MJML v3 had added validation for templates and it breaks mjml-ruby v0.2.x if your template was invalid. mjml-ruby > v0.3.x has validation_level option(:soft by default) and allows to use old templates with v3. All validation errors will be logged.

Example:

MJML.configure do |config|
  config.validation_level = :soft # :skip/:soft/:strict
end

With Rails

<!-- app/views/layouts/mailer.html.mjml -->

<mjml>
  <mj-body>
    <mj-container>
      <%= yield %>
    </mj-container>
  <mj-body>
</mjml>

<!-- app/views/welcome_mailer/welcome.html.mjml -->

<mj-text>Hello, <%= @user.name %></mj-text>

class WelcomeMailer < ApplicationMailer
  def welcome(user)
    @user = user
    mail(to: @user.email, subject: 'Welcome')
  end
end

With Tilt

<!-- templates/hello.mjml -->

<mjml>
  <mj-body>
    <mj-container>
      <mj-text>Hello, world!</mj-text>
    </mj-container>
  <mj-body>
</mjml>

require 'tilt'
require 'mjml'

template = Tilt.new('templates/hello.mjml')
template.render # returns compiled HTML

With mail gem

<!-- hello.mjml -->

<mjml>
  <mj-body>
    <mj-container>
      <mj-text>Hello, world!</mj-text>
    </mj-container>
  <mj-body>
</mjml>

require 'mail'
require 'mjml'

template = File.open('hello.mjml', 'rb') { |f| MJML::Parser.new.call(f) }

Mail.deliver do
  from '[email protected]'
  to '[email protected]'
  subject 'Hello'
  body template
end

Configuration

# Change default mjml executable

# Regular Ruby
MJML.configure do |config|
  config.bin_path = '/usr/bin/env mjml'
  config.logger = YourLogger.new(STDOUT)
  config.minify_output = true
  config.validation_level = :soft
end

# Rails
Rails.application.configure do
  config.mjml.bin_path = '/usr/bin/env mjml'
  config.mjml.logger = MJML::Logger.setup!(STDOUT)
  config.mjml.minify_output = true
  config.mjml.validation_level = :soft
end

Deprecations

v0.3

• config.debug = true is deprecated. If you are using default MJML Logger use config.logger.level = ::Logger::DEBUG instead.

TODO

• Create parser
• Make it configurable
• Create Tilt interface
• Create Sprockets interface
• Create Railtie
• Setup Travis
• Add usage guide
• Fix tests on CI
• Add more tests
• Improove docs