Skip to content
This repository
tree: a17e5e2462
Fetching contributors…

Cannot retrieve contributors at this time

file 73 lines (45 sloc) 4.957 kb

Getting Started with Engines

In this guide you will learn about engines and how they can be used to provide additional functionality to their host applications through a clean and very easy-to-use interface. You will learn the following things in this guide:

  • What are engines
  • Generating an engine
  • Building features for the engine
  • Hooking the engine into an application
  • Overriding engine functionality in the application

endprologue.

What are engines?

Engines can be considered miniature applications that provide functionality to their host applications. A Rails application is actually just a “supercharged” engine, with the Rails::Application class inheriting from Rails::Engine. Therefore, engines and applications share common functionality but are at the same time two separate beasts. Engines and applications also share a common structure, as you’ll see later in this guide.

Engines are also closely related to plugins where the two share a common lib directory structure and are both generated using the rails plugin new generator.

The engine that will be generated for this guide will be called “blorgh”. The engine will provide blogging functionality to its host applications, allowing for new posts and comments to be created. For now, you will be working solely within the engine itself and in later sections you’ll see how to hook it into an application.

Engines can also be isolated from their host applications. This means that an application is able to have a path provided by a routing helper such as posts_path and use an engine also that provides a path also called posts_path, and the two would not clash. Along with this, controllers, models and table names are also namespaced. You’ll see how to do this later in this guide.

To see demonstrations of other engines, check out Devise, an engine that provides authentication for its parent applications, or Forem, an engine that provides forum functionality.

Generating an engine

To generate an engine with Rails 3.1, you will need to run the plugin generator and pass it the —mountable option. To generate the beginnings of the “blorgh” engine you will need to run this command in a terminal:

$ rails plugin new blorgh —mountable

The —mountable option tells the plugin generator that you want to create an engine (which is a mountable plugin, hence the option name), creating the basic directory structure of an engine by providing things such as the foundations of an app folder, as well a config/routes.rb file. This generator also provides a file at lib/blorgh/engine.rb which is identical in function to an application’s config/application.rb file.

Inside the app directory there lives the standard assets, controllers, helpers, mailers, models and views directories that you should be familiar with from an application.

At the root of the engine’s directory, lives a blorgh.gemspec file. When you include the engine into the application later on, you will do so with this line in a Rails application’s Gemfile:

gem ‘blorgh’, :path => “vendor/engines/blorgh”

By specifying it as a gem within the Gemfile, Bundler will load it as such, parsing this blorgh.gemspec file and requiring a file within the lib directory called lib/blorgh.rb. This file requires the blorgh/engine.rb file (located at lib/blorgh/engine.rb) and defines a base module called Blorgh.

require “blorgh/engine”

module Blorgh
end

Within lib/blorgh/engine.rb is the base class for the engine:

TODO: lib/blorgh/engine.rb

Within the app/controllers directory there is a blorgh directory and inside that a file called application_controller.rb. This file will provide any common functionality for the controllers of the engine. The blorgh directory is where the other controllers for the engine will go. By placing them within this namespaced directory, you prevent them from possibly clashing with identically-named controllers within other engines or even within the application.

Providing engine functionality

TODO: Brief explanation of what this engine is going to be doing and what we will have once we are done.
TODO: Generate a posts scaffold (maybe?) for the engine
TODO: Generate a comments scaffold (maybe?) for the engine

Hooking into application

TODO: Application will provide a User foundation class which the engine hooks into through a configuration setting, configurable in the application’s initializers. The engine will be mounted at the /blog path in the application.

Overriding engine functionality

TODO: Cover how to override engine functionality in the engine, such as controllers and views.
IDEA: I like Devise’s devise :controllers => { “sessions” => “sessions” } idea. Perhaps we could incorporate that into the guide?

Something went wrong with that request. Please try again.