The Core Module: Set Up

4.4.1. The engines folder

In order to keep our code organised, we will create an engines/ folder, and move the Core engine inside. All our engines will go inside this directory. We will then move into the core engine’s directory:

mkdir engines && mv core engines/ && cd engines/core

4.4.2. Add one more namespace level

On creation, everything inside an engine will only be namespaced based on its name. Since we are building a modular application and a set of engines that are supposed to work together, we recommend adding one global namespace to keep them grouped. For this application, we will use the namespace Blast.

For now, let’s focus on the lib folder located at blast_crm/engines/core/lib. In this folder we’ll find the heart of our engine, but first we have to do a bit of reorganising.

Rearrange the lib folder until you have the structure shown in Listing 3. To achieve this result, run the following command from blast_crm/engines/core/ to create and update the relevant files and match the new structure:

cd lib && mkdir blast && mv core core.rb blast/ && touch blast_core.rb

blast_crm/engines/core/
  lib/
    blast_core.rb
    blast/
      core.rb
      core/
        engine.rb
        version.rb

4.4.3. blast_core.rb and core.rb

Before we write any actual code, we need to update the require paths in blast_core.rb and core.rb, to allow the parent application to discover the content of our engine, as shown in Listing 4 and Listing 5:

require 'blast/core'

require_relative 'core/engine'

module Blast
  module Core
  end
end

4.4.4. Define a version

In the future, the Core engine might be released as a gem, so we should give it a proper version straight away. We also need to add the top-level namespace (Blast), as shown in Listing 6:

module Blast
  module Core
    VERSION = '0.1.0'
  end
end

4.4.5. The Engine file

Each Ruby on Rails engine comes with a file named engine.rb. This file represents the heart of the engine. Since we’ve changed the structure of the engine, we need to add our new global namespace to this file, as well as remove the Core namespace from the isolate_namespace method (see Listing 7).

We won’t be namespacing the models and controllers with Core in the Core module. You will understand why in the next chapter, but for now, you should know that it makes extending the Core much easier.

module Blast
  module Core
    class Engine < ::Rails::Engine
      isolate_namespace Blast
    end
  end
end

4.4.6. Gemspec

Next, we need to fix the gemspec file for our Core engine, located at blast_crm/engines/core/core.gemspec.

First, we need to rename the file to blast_core.gemspec to match the namespaces we are now using. Run this command from the blast_crm/engines/core directory:

mv core.gemspec blast_core.gemspec

Then, we need to adjust some of the require paths and put some actual information in the specification.

Here’s the file with the changes:

$LOAD_PATH.push File.expand_path('lib', __dir__)

# Maintain your gem's version:
require 'blast/core/version'

# Describe your gem and declare its dependencies:
Gem::Specification.new do |spec|
  spec.name        = 'blast_core'
  spec.version     = Blast::Core::VERSION
  spec.authors     = ['Devblast']
  spec.email       = ['info@devblast.com']
  spec.homepage    = 'https://devblast.com'
  spec.summary     = 'Core features of blast_crm.'
  spec.description = 'Core features of blast_crm.'
  spec.license     = 'MIT'

  # Prevent pushing this gem to RubyGems.org.
  # To allow pushes either set the 'allowed_push_host'
  # to allow pushing to a single host or delete this section
  # to allow pushing to any host.
  if spec.respond_to?(:metadata)
    spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
  else
    raise 'RubyGems 2.0 or newer is required to protect against ' \
      'public gem pushes.'
  end

  spec.files = Dir['{app,config,db,lib}/**/*', 'MIT-LICENSE',
                   'Rakefile', 'README.md']

  spec.add_dependency 'rails', '~> 5.2.3'

  spec.add_development_dependency 'sqlite3', '~> 1.4.1'
end

That’s it for the gemspec file.

4.4.7. bin/rails

To make everything work smoothly, we need to change one small thing inside the engines/core/bin/rails file: We need to add blast to the ENGINE_PATH, as shown in Listing 9.

#!/usr/bin/env ruby
# This command will automatically be run when you run "rails" with Rails gems
# installed from the root of your application.

ENGINE_ROOT = File.expand_path('..', __dir__)

# We changed the following line
ENGINE_PATH = File.expand_path('../lib/blast/core/engine', __dir__)

# Set up gems listed in the Gemfile.
ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])

require "rails"
# Pick the frameworks you want:
require "active_model/railtie"
require "active_job/railtie"
require "active_record/railtie"
require "active_storage/engine"
require "action_controller/railtie"
require "action_mailer/railtie"
require "action_view/railtie"
require "action_cable/engine"
require "sprockets/railtie"
# require "rails/test_unit/railtie"
require 'rails/engine/commands'

4.4.8. The Core routes

Now we need to deal with the routes.rb file. If you open the routes file for the Core engine located at blast_crm/engines/core/config/routes.rb, you will see that the Blast namespace is missing. Let’s add it as shown in Listing 10

Blast::Core::Engine.routes.draw do
end

4.4.9. Adding the module to the parent Gemfile

Let’s tie everything together. Go back to the parent application and open the blast_crm/Gemfile file. All we have to do now is add our module. If your Gemfile already contains the line gem 'core', path: 'core', update it to the value below. If not, simply add it at the end of the file:

.
.
.

gem 'tzinfo-data', platforms: %i[mingw mswin x64_mingw jruby]

# We added/updated the following line
gem 'blast_core', path: './engines/core'

4.10 Get the dependencies

Now, do a quick bundle install from the parent application and everything should work! If not, review the setup and see if you have changed everything correctly.

bundle install

If you’ve set up everything properly, the dependencies should be resolved without issues.

4.11 Mount the engine

The Core module is now integrated inside the parent application, but it’s not actually accessible yet. For that, we need to mount it inside the parent application’s routes file:

Rails.application.routes.draw do
  mount Blast::Core::Engine => '/', as: 'blast'
end

4.12 Am I alive? Can you see me?

Et voila, we are done with the setup. You should be able to start your Rails server now, but you will end up on the default Rails page if you try to access it. How about adding some content?

4.5.1. Reorganize the controllers folder

The first step, before continuing, is to rearrange the controllers folder inside the Core engine. Since we will be using Blast to namespace our Core controllers instead of Core, we need to rename the core/ folder. Here’s a command you can run from the engine folder (engines/core/) to get the structure we want:

mv app/controllers/core app/controllers/blast

Your controllers folder should look like the Listing 13:

engines/core/app/
 controllers/
   blast/
     application_controller.rb

We also need to update the engine’s ApplicationController to what is show in Listing 14:

module Blast
  class ApplicationController < ActionController::Base
    protect_from_forgery with: :exception
  end
end

4.5.2. Create the Dashboard controller

Now, we can create the Dashboard controller, which will only contain an index action. The command to create it is below, which you must run from inside the engine:

touch app/controllers/blast/dashboard_controller.rb

Listing 15 shows what content we must provide:

module Blast
  class DashboardController < ApplicationController
    def index
    end
  end
end

4.5.3. Add the corresponding route

And for the route of this controller:

Blast::Core::Engine.routes.draw do
  root to: 'dashboard#index'
end

Now, let’s try to access the application. Run rails s and head over to localhost:3000. Or don’t, because it’s going to crash anyway. We have to fix the views before we can see anything.

4.5.4. Fix the layout and add the index view for the dashboard

Once again, due to the namespace we added, we need to create an extra folder for the views. Change your views folder until you have the structure below (or simply run the command from within engines/core/):

mv app/views/layouts/core app/views/layouts/blast && \
mkdir -p app/views/blast/dashboard && \
touch app/views/blast/dashboard/index.html.erb

blast_crm/engines/core/app
 views/
   layouts/
     blast/
       application.html.erb
   blast/
     dashboard/
       index.html.erb

Now, if you access localhost:3000, the application works and returns a beautiful white screen.

rails g controller dashboard --no-assets --no-helper

4.6.1. Add the gems

We’re going to use the Bootstrap Ruby Gem to style BlastCRM. To do this, we need to add a few gems to the gemspec of the Core engine, as show in Listing 18.

  .
  .
  .
  spec.add_dependency 'rails', '~> 5.2.3'

  spec.add_dependency 'bootstrap', '~> 4.3.1'
  spec.add_dependency 'jquery-rails', '~> 4.3.3'
  spec.add_dependency 'sass-rails', '~> 5.0'

  spec.add_development_dependency 'sqlite3', '~> 1.4.1'
end

When used inside an engine, gems are not automatically loaded. To load them, we need to require them inside blast_crm/engines/core/lib/blast/core.rb, as you can see below:

require_relative 'core/engine'
require 'sass-rails'
require 'bootstrap'
require 'jquery-rails'

module Blast
  module Core
  end
end

Keep this in mind when you start working on your own engines.

Let’s run bundle install from the parent application to get everything installed. Don’t forget to restart your server.

4.6.2. Fix the assets folder

Once again, we have to fix and rearrange the assets folder to add one more level. Change your assets folder inside the Core engine to look like it does in Listing 20, or use the following commands (run them from within the Core engine folder):

mv app/assets/images/core app/assets/images/blast &&
mv app/assets/javascripts/core app/assets/javascripts/blast &&
mv app/assets/stylesheets/core app/assets/stylesheets/blast

assets/
 images/
   blast/
 javascripts/
   blast/
     application.js
 stylesheets/
   blast/
     application.css

4.6.3. Load the Bootstrap CSS

Since we’re going to use Bootstrap, we need to change the application.css file. Simply rename it to application.css.scss and change its content to that of Listing 20:

mv app/assets/stylesheets/blast/application.css \
   app/assets/stylesheets/blast/application.css.scss

@import "bootstrap";

4.6.4. Load the Bootstrap JavaScript files

Let’s add the Bootstrap javascript files in the application.js file:

//= require rails-ujs
//= require activestorage
//= require jquery3
//= require popper
//= require bootstrap
//= require_tree .

Time to write some HTML.

4.6.5. Update the layout file

Because we’ve changed the assets folder structure, we need to update the layout file by changing the stylesheet and javascript inclusion links. We need to prefix them with blast/ instead of core/:

<!DOCTYPE html>
<html>
  <head>
    <title>BlastCRM</title>
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>

    <%= stylesheet_link_tag    "blast/application", media: "all" %>
    <%= javascript_include_tag "blast/application" %>
  </head>
  <body>

    <%= yield %>

  </body>
</html>

4.6.6. Add content to the layout file

Since we added Bootstrap, let’s leverage it. We’re going to update the file we’ve just modified with some content. Paste the code from Listing 24 in the <body> tag of the application.html.erb file, so that the file can look like Listing 25:

<nav class="navbar navbar-expand-lg navbar-light bg-light
            navbar-inverse navbar-fixed-top mb-4">
  <%= link_to 'BlastCRM', blast.root_path, class: 'navbar-brand' %>
</nav>

<div class='container' role='main'>
  <%= yield %>
</div>

<!DOCTYPE html>
<html>
  <head>
    <title>BlastCRM</title>
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>

    <%= stylesheet_link_tag    "blast/application", media: "all" %>
    <%= javascript_include_tag "blast/application" %>
  </head>
  <body>
    <nav class="navbar navbar-expand-lg navbar-light bg-light
                navbar-inverse navbar-fixed-top mb-4">
      <%= link_to 'BlastCRM', blast.root_path, class: 'navbar-brand' %>
    </nav>

    <div class='container' role='main'>
      <%= yield %>
    </div>
  </body>
</html>

This is some pretty regular Bootstrap usage. We added a navbar that will contain the links of our menu, and we surrounded the yield call with the container class provided by Bootstrap. The jumbotron is just here to add a bit of style and break with the blank design.

Something important to note, however, is the use of blast.root_path. Why don’t we just put root_path? Well, it’s due to the Devise gem. Without blast in front of every route, the app will crash when we try to access the views from Devise in the future. There is some kind of path conflict when using Devise inside a namespaced engine. Regardless, it is good practice to prefix all our paths with our namespace (blast) in order to avoid any potential problem in the future.

If you check your browser, you should see what is shown in Figure 1.

Figure 1: So white… So empty....

4.6.7. Add a title to the dashboard

The last step before creating our first model, is to give a title to the blank dashboard. Just add the following code to the dashboard index view.

<h2>Dashboard</h2>
<hr>

Figure 2: Now, it looks pretty good... right?

4.7.1. Installing Git

brew install git

sudo apt-get install git

4.7.2. The Initial Commit

The first thing we need to do is to tell Git that we want to version the current project. At the root of the project, run the following command:

git init

Then we are going to stage all the files as ready to be committed:

git add .

Finally, we can commit the staged changes:

git commit -m "Initial Commit"

You can create an account on GitHub if you want to push your changes to a remote repository. If you prefer to store your repositories on your own servers, there are plenty of alternatives, like Gitolite. We’ll be using GitHub as an example for the rest of this book.

Once you’ve signed up and created a repository, grab the URL and add it as the origin for your repository with:

git remote add origin YOUR-GITHUB-REPO-URL

Don’t forget to replace YOUR-GITHUB-REPO-URL with an actual URL.

Finally, we can push all our local changes to the remote repository on GitHub, using the git push command.

git push origin master

4.8.1. What did we learn?

• Engines are generated with rails plugin new core --mountable
• We need an empty Ruby on Rails application to hold our engines as gems
• When using gems inside an engine, they need to be required when the engine is loaded

4.8.2. Next Step

In the next chapter, we’ll work on restricting the access to BlastCRM through authentication.