[GUIDE] MDBootstrap Integration with Ruby on Rails

I see several Rails developers asking how to integrate the amazing MDBootstrap with their Rails applications. Since the MDBootstrap team doesn’t work directly in Rails, this can be a tricky question to address in the Rails context.

As a Rails developer myself, I grappled with this a bit, and I wanted to share my step-by-step process for getting MDBootstrap up and running:

rails new app_name

In your gemfile, add

gem 'jquery-rails'
gem 'font-awesome-rails'

then

bundle install

Download your particular MDB version and extract it some place handy.

Create the following paths in your app:

vendor/assets/javascripts
vendor/assets/stylesheets

Inside

vendor/assets/javascripts

place the following MDB assets:
bootstrap.js
mdb.js
popper.min.js
custom.js

Inside

vendor/assets/stylesheets

place the following assets:
bootstrap.css
mdb.css
custom.css

Inside your javascript manifest

app/assets/javascripts/application.js

set up your requires as follows:

//= require jquery
//= require popper.min
//= require bootstrap
//= require mdb
//= require custom
//= require rails-ujs
//= require activestorage
//= require turbolinks
//= require_tree .

Do not use require_tree with a relative path to add your entire vendor/assets/javascripts folder as Rails will execute
them in alphabetical order and create rendering issues on the front end. Require them individually as above.

Inside your CSS manifest

app/assets/stylesheets/application.css.scss

set up your requires as follows:

 *= require font-awesome
 *= require bootstrap
 *= require mdb
 *= require_tree .
 *= require_self

How to get the font working

Now, you'll need to deal with the provided web font 'Roboto'.

Create the path:

app/assets/font

and place the roboto folder in it so the path looks like

app/assets/font/roboto/<files here>

You'll need to tell Rails to include the font path in the asset pipeline. To do this, add:

config.assets.paths << Rails.root.join("app", "assets", "font", "roboto")

in your

config/application.rb

file.

Now you'll need to address the font path references in the mdb.css file. By default, the @font-face styles are defined like:

@font-face {
 font-family: Roboto;
 src: local(Roboto-Thin),
   url(../font/roboto/Roboto-Thin.eot);
 src: url(../font/roboto/Roboto-Thin.eot?#iefix) format("embedded-opentype"),
   url(../font/roboto/Roboto-Thin.woff2) format("woff2"),
   url(../font/roboto/Roboto-Thin.woff) format("woff"),
   url(../font/roboto/Roboto-Thin.ttf) format("truetype");
   font-weight:200
}

This will block rendering of your Rails app as it looks for invalid font references and searches for a replacement font when not found. This is obviously bad.

In mdb.css you'll need to modify the CSS @font-face styles so they look like the following:

@font-face {
 font-family: Roboto;
 src: url(/assets/Roboto-Thin.eot);
 src: url(/assets/Roboto-Thin.eot?#iefix) format("embedded-opentype"), 
   url(/assets/Roboto-Thin.woff2) format("woff2"), 
   url(/assets/Roboto-Thin.woff) format("woff"), 
   url(/assets/Roboto-Thin.ttf) format("truetype");
   font-weight: 200
}

You'll need to do this for ALL weights of Roboto (regular, bold, etc) defined in the mdb.css or you'll continue to get reference errors and render blocking issues as you call different classes in your app.

Be sure to inspect element and look at console errors to verify all fonts are being correctly referenced.

How to get Lightbox, Carousel, and their assets working

The process is exactly the same as getting the font to work.  You'll need to add the mdb-addons and img folders to

vendor/assets

Then as you did with the fonts, add the asset paths to config/application.rb

config.assets.paths << Rails.root.join("vendor", "assets", "img")
config.assets.paths << Rails.root.join("vendor", "assets", "mdb-addons")

Then open your mdb.css file and locate the URL references to these assets, and change them the same way you did for the font.

Here are some examples of what the CSS path changes should look like for the lightbox controls, overlays, and svg  folders:

.pswp__button,
.pswp__button--arrow--left:before,
.pswp__button--arrow--right:before {
 background: url(/assets/lightbox/default-skin.png) 0 0 no-repeat;
 -webkit-background-size: 264px 88px;
 background-size: 264px 88px;
 width: 44px;
 height: 44px; }

.pattern-1 {
 background: url("/assets/overlays/01.png"); }

.carousel .carousel-control-prev-icon {
 background-image: url(/assets/svg/arrow_left.svg); }

How do I use specific MDB js modules on specific pages?

In your

application.html.erb

file, use embedded Ruby to define a body class as follows:

<body class="<%= controller_name %> <%= action_name %>">
 <%= yield %>
</body>

Let's say there is a request for the following route: root 'home#index'

The

<body>

tag for this page will be render as

<body class="home index">

in the DOM.

Now you can easily target the DOM with some custom JS using the body class ".home.index".

Let's say you want to use the Datepicker module ONLY on the this page.

You'll achieve this by adding the Datepicker jQuery provided by MDB to your custom.js in your

vendor/assets/javascripts/custom.js

path with a .ready wrapper like this:

$('.home.index').ready(function(){
  $('.datepicker').pickadate({
     weekdaysShort: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'],
     showMonthsShort: true
  });
 
  $('.some-other-class').somemdbmethod({
     // Code here
  });
});

When your app loads, application.html.erb loads once, and all of your assets will be loaded once as well.  The only things that change are what view is displayed in <%= yield %> and the <body> tag which will have a class name that changes dynamically based on controller#action.

So while your custom jQuery is loaded once due to Rails convention, all of the methods are properly scoped to their respective views.

Hope this helps!

Credits:
Brandon Hilkert @ brandonhilkert.com
anotheruiguy @ github