This document provides an introduction to setting up and testing Rails 3 engines. It discusses how engines were revamped in Rails 3 based on influences from Merb, and explains that engines inherit from Railties. It also demonstrates how to configure an engine's paths, bundle an engine as a gem, and share assets between an engine and host application. Finally, it summarizes best practices for testing engines and provides contact information for discussions on engines.

1. HOW TO SETUP AND
TEST RAILS 3 ENGINES.
Nicholas Faiz,
Tree Falling In The Woods, Pty Ltd.

2. INTRO
A quick introduction to Engines in Rails 3, including
a demo of how to set one up and test it.
Background: I've been working on a Rails 3 engine
project since February or so. It might help if I share
what I've encountered so far.
Rails 3 Engines are new. Rails 3 RC 2 only released a
few days ago.

3. INTRO 2
Finding information on how to set up an Engine in
Rails 3 has been difficult. Useful blogs: http://
www.themodestrubyist.com - by Jordan West. 4 posts
about engines.
Cesario: http://www.dev-fr.com/archives/
2010/04/07/rails-3-railties-and-engines/

4. STORY OF ENGINES SO
FAR
Engines before Rails 2.3
Engines Incorporated 2.3
Engines revamped in Rails 3

5. STORY OF ENGINES ... 2
How were they revamped in Rails 3? Merb influence
of decoupling.
2009 Merb merged with Rails. Merb influence r.e.
decoupled dependencies! e.g. Should be able to use
whichever ORM in your MVC.
In Rails 3 engines revamped, now inherit from
Rails::Railtie (See the Merb influence)

6. WHAT ARE RAILTIES?
Railties are a central concept to Rails 3. They
decouple components from each other.
See http://railsapi.com/doc/rails-v3.0.0.beta.3/
classes/Rails/Railtie.html
All major aspects of the Rails Framework are now
assembled into a larger system via a collection of
Railties.

7. WHAT ARE RAILTIES? 2
ActionController::Railtie < Rails::Railtie,
ActionView::Railtie < Rails::Railtie, etc.
Railties carry initializers, letting you configure how a
Rails application is bootstrapped.’
initializer "configure something" {|app|
config.something()}

8. WHAT ARE ENGINES?
Rails 3: Engines *are* Railties, well, subclasses of
them.
Rails::Engine < Rails::Railties
In fact, every Rails application *is* an engine, well, a
subclass ...
Rails::Application < Rails::Engine

9. WHAT ARE ENGINES?
Only touching upon functionality in this
presentation.
Hosting applications can use them, or override them
if they want to change things.
Most known Rails 3 engine at the moment - Devise:
http://github.com/plataformatec/devise

10. CONFIGURE, BUNDLE,
TEST
Engines are a bit more than just a Rails application,
though. More to it than the API. You have to know
how to configure, bundle, and test it.
You bundle a Rails engine, in its own gem, to reuse
within another Rails application.
First understand how an engine is accessed and used
by a Rails application.
Standard Rails app. paths available in the engine ...

11. ENGINE PATHS
class MyEngine < Rails::Engine
paths.app = "app"
paths.app.controllers = "app/controllers"
paths.app.helpers = "app/helpers"
paths.app.models = "app/models"
paths.app.metals = "app/metal"
paths.app.views = "app/views"
paths.lib = "lib"
paths.lib.tasks = "lib/tasks"
paths.config = "config"
paths.config.initializers = "config/initializers"
paths.config.locales = "config/locales"
paths.config.routes = "config/routes.rb"
end

12. ENGINES INSIDE THE
HOST APP.
All of this information is addressable via the Rails
object.
ruby-1.8.7-p299 > Rails.application.railties.engines
Holds an array of engine objects.

13. PATHS IN RAILS
ENGINES
rails console
ruby-1.8.7-p299 > e = Rails.application.railties.engines.last
ruby-1.8.7-p299 > e.config.paths.app
a => #<Rails::Paths::Path:0x103bf7058 @eager_load=true, @root=#<Rails::Paths::Root:
0x103c02958 @all_paths=[#<Rails::Paths::Path:0x103bf7058 ...>, …, @paths=["app"]>
ruby-1.8.7-p299 > e.class.name
=> "InklingContent::Engine" #helps to give your Railtie an informative namespace

14. FINDING AN ENGINE
BLUEPRINT
I began working on my own engines and made
headway in some areas but not others.
I decided that I wanted a simple blueprint of how an
engine should look.
Because engines are new, there aren't established
practices for setting them up and testing them. I've
come up with my own, which seem like common
sense, but took some thought.

15. TOMMY THE RAILS 3
ENGINE!
So I created Tommy, a
simple application with
a picture of Tommy the
Tank engine repeating a
message held in sqlite.

16. HOW IS SOMETHING SO
SIMPLE HELPFUL?
Demonstrates some basic concepts. Some projects
would actually copy their static files - javascripts,
partials, etc. - *over* the hosting application. (e.g.
BrowserCMS), in the Rails 2.x days.
I needed to prove how sharing assets was done
without this intrusion in Rails 3.

17. IN DEMO LOOK FOR ...
The Railties file (the engine).
Generators for migrations.
How to share static assets (like images, stylesheets,
javascript files, etc.), from the engine into the host
engine.
How to share rake tasks.
How to configure rspec and cucumber in an engine.

18. TOMMY THE RAILS 3
ENGINE DEMO
http://github.com/biv/tommy

19. SUMMATION
An engine can't be used without a functioning Rails
app.. I find it easiest to nest a Rails app beneath the
top directory.
Tests for the engine can be created at the top level
directory of the engine, but symlinked into the test
app..

20. SUMMATION 2
Rails 3 engines are new. I haven’t heard many stories,
yet, about how they perform in production settings.

21. CONTACT ME TO
DISCUSS ENGINES
I’m basing a lot of work in 2010/2011 on the Engine
structure. I’m happy to discuss them:
biv/brain_in_vat on #roro freenode
http://twitter.com/nicholasf