MD Bootstrap Ruby on Rails tutorial

Published 11.12.2018 Updated 14.12.2018

Jakub Strebeyko posted 1 months ago

Kudos go to kenc138 for preparing the original version of this guide.

Today you will learn how to get your Ruby on Rails project totally MDBed!

Ruby language syntax is easy to understand, while Rails help developers increase their productivity by allowing them to focus on designing and implementing features, and not worrying about setting up server connections or planning out the folder structure. Last but not least, the framework is open source.

If you notice an error, or something below is not clear to you - we invite you to visit our support forum.

What will I learn?

Where to drop all your favorite scripts and styles
How to inlude them into Rails assets pipeline, so they are ready to go
How to test SCSS compilation and make sure it all goes smoothly
Having resources loaded only when necessitated by targeted views

Note, that the guide takes you from the bottom up, and its two first steps are to be omitted by people who already have their projects ready.

1. Get yourself some Rails:
Make sure you have all it takes to start a new project:

1.1 Open up a command line prompt. On macOS open Terminal.app, on Windows choose "Run" from your Start menu and type 'cmd.exe'. Any commands prefaced with a dollar sign $ should be run in the command line. Verify that you have a current version of Ruby installed:
```
  ruby -v
```
1.2 Rails requires Ruby version 2.2.2 or later. If the version number returned is less than that number, you'll need to install a fresh copy of Ruby.
1.3 A number of tools exist to help you quickly install Ruby and Ruby on Rails on your system. Windows users can use Rails Installer, while macOS users can use Tokaido. For more installation methods for most Operating Systems take a look at ruby-lang.org.
1.4 If you are working on Windows, you should also install the Ruby Installer Development Kit.
1.5 You will also need an installation of the SQLite3 database. Many popular UNIX-like OSes ship with an acceptable version of SQLite3. On Windows, if you installed Rails through Rails Installer, you already have SQLite installed. Others can find installation instructions at the SQLite3 website. Verify that it is correctly installed and in your PATH:
```
  sqlite3 --version 
```
The program should report its version.
1.6 To install Rails, use the gem install command provided by RubyGems:
```
  gem install rails 
```
1.7 To verify that you have everything installed correctly, you should be able to run the following:
```
  rails --version 
```
1.8 If it says something like "Rails 5.2.1", you are ready to continue!

2. Preparing the project:

  rails new yourappnamehere

The CLI will then inquire about your RubyGems password - if you don't have one, no problem - just press CTRL + C.

  cd yourappnamehere

To install gems, simply hit

  bundle install --path vendor/bundle

from within the project root directory.

3. Time to get the basic gems! It your project does not use them already, go to ./Gemfile and add these, preferably around lines 29 / 30:

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

bundle install

5. Time to get real & get your MDB package somewhere handy.
Create /vendor/assets/javascirpts/ directory in your rails project, and move these bad-boys inside:

bootstrap.js
mdb.js
popper.min.js

6. Create, similarly, a /vendor/assets/stylesheets/ directory, and place our blazing styles inside for them to reign:

bootstrap.css
mdb.css

7. Adding JavaScript
Ok, now, the doctor is in! Time to have some little work done on the JavaScript Manifest. It defines what scripts exactly get processed in the so-called "asset pipeline" - it is the crucial point for attaching your custom scripts to a Rails project. Go, look it up at app/assets/javascripts/application.js, and since you are there, rearrange the scripts list so it looks as follows:

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

These might look weird and commented out, but fear not! This is the file Rails uses to know what and from where to take and concatinate, fingerprint and attach to whatever you're building.

8. Adding CSS
All right, plot twist time! There is also a CSS Manifest, that does the same things, but with stylesheets! It lives at app/assets/stylesheets/application.css, give it a knock and see what can it do for you today. Make sure the asset list looks like this:

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

A default project pipeline is ready to compile Sass, too! It is really handy by itself, but also in debugging - in case of some CSS inconsistencies, the stylesheet pipeline may fail silently, resulting in not having them included into the outputted file. For debugging of this process, you can try to precompile .scss files using Rake:

  rake assets:precompile --trace

9. Adding Roboto Font
Time for something entirely different! We want the font files to be attached to the end product of our work, but there is no Font Manifest this time. Create a app/assets/font/ directory if it's not there and put the /roboto font folder inside. Now navigate to config/application.rb and add the following to line 13:

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

10. Tweaking the CSS file
Since we moved the stylesheets into a different project, our CSS url() function points to a wrong place! To address this change, we have to modify our mdb.css file a little. Find instances of @font-face and replace their url()function parameter with appropriate directory, also - get rid of the local syntax for Rails to have no silly ideas:

   @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
   }

11. Running your project
Almost there! Make sure that the template (by default found at vendor/bundle/ruby/2.3.0/gems/railties-5.2.0/lib/rails/templates/rails/welcome/index.html.erb) is bootstrapped with our output files! To do so, see whether it contains appropriate tags:

   <%= stylesheet_link_tag "application", :media => "all" %>
   <%= javascript_include_tag "application" %>

There is a possibility you might have to alter project's default Content Security Policy, so it allows for attached scripts and stylesheets.

12. Using MDB add-ons
It is what we just did here - getting assets on starting blocks and connecting them to the assets pipeline. Copy img and mdb-addons to /vendor/assets and update your config/application.rb file to include these:

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

Similarly as the Roboto font, here we also need to tweak urls in our CSS, replacing ../img/ with /assets/:

   .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); }

13. Extra: getting specific MDB JavaScript Modules work on specific pages only:
In your application.html.erb file, use embedded Ruby to define a body class as follows:

  <%= yield %>

Now, if there is a request for the home#index route, The <body> tag for this page will be render as <body class="home index"> in the DOM. Now it is possible to target the DOM with JS using .home.index selector. If, say, you would like a Date Picker being uploaded only in a particular page of your app, you can do this by surrounding the contents of your vendor/assets/javascripts/custom.js with a 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 so do all of your assets. That way <body> tag has dynamically changing class names that depend on controller#action, what changes is <%= yield %>, dynamic substitutes of which are properly scoped to their respective views.