Rails Engines

Hi, I’m Josh

I work here ->

lvlsvn.com

We Build Ruby AppsAnd a bunch of other stuff

We also do design

We also do design

The designers had NOTHING to do with my slides.

Here’s the Problem

Even custom applications want to be able to manage their static pages

Think Contact Us, Team Bios, etc.

Wordpress, Drupal even Locomotive are great but heavy weight

What we needed

A mini-cms

Uses our existing rails views

No subdomaining, feels like part of the app

Works with our authentication setup

Great for 4 or 5 pages of content

OptionsHigh Voltage

https://github.com/thoughtbot/high_voltage

Great for devs, not great for the customer

Locomotive Engine

http://locomotivecms.com/

Awesome but heavyweight, assumes their template style

Exstatic

https://github.com/LevelSeven/exstatic

WARNING: Not even close to finished

Works w/ devise

Mounts in another application

Inherits that application’s layouts

But how?

Rails Engines

obviously, otherwise this talk wouldn’t make much sense

What are Rails Engines?Lesser known feature, started in Rails 3.0

Mini-application that can be added to a larger rails app

Replace plugins

Are a subset of Railties, so you can use railtie stuff (like generators, rake tasks, etc.)

Why?

Code reuse

Share functional components

Share business logic

Isolation

Distribution

Open Source part of a private app

Creating an Engine2 Ways

Rails 3.1 or greater

> rails plugin new

Rails 3.0

Use enginex by Jose Valim

https://github.com/josevalim/enginex

$> rails plugin new depot_engine --dummy-path=spec/dummy --skip-test-unit --mountable --skip-bundle

...

--dummy-path=spec/

$>

rails plugin new depot_engine

dummy --skip-test-unit --mountable --skip-bundle

Creates a new Rails Engine with the name DepotEngine

--dummy-path=spec/

$>

rails plugin new depot_engine --skip-test-unit --mountable --skip-bundle

Creates a fake rails app in the RSpec path

dummy

--dummy-path=spec/

$>

rails plugin new depot_engine

--mountable

Sets the engine to be “mountable” as opposed to “full”

Full - the parent inherits routes from the engine and can directly access it’s components (controllers, models, etc.)

Mountable - the engine’s namespace is isolated and draws its own routes. It mounts at a path:

mount DepotEngine::Engine => “/store”, :as => “store”

dummy--skip-test-unit --skip-bundle

Setting Up RSpec

Add rspec-rails to development dependencies in gemspec

bundle install

rails g rspec:install

Set rspec as test_framework in engine.rb

lib/engine_name/engine.rb

Testing through dummy rails plugin new automatically creates a dummy app

Rails.application is available to test initializers

Rails.application.routes will get you dummy app routes

More in a bit

Depot as an Engine

Depot application

github.com/levelseven/depot_engine

Migration Pitfalls

You have to use the engine name everywhere

rails g migration add_foo_to_engine_name_table_name

To copy migrations into dummy app cd into dummy and run

rake engine_name:install:migrations

Asset Pipeline PitfallsAssets have to be preceeded by engine_name in view helpers

image_tag(‘engine_name/logo.png’)

Copy assets group in Gemfile from normal rails app into Gemfile in engine, then bundle install in dummy app

View Hints

You can reference parent via main_app helper

i.e. link_to “Home”, main_app.root_path

Use the parent’s layouts by adding layout “application” to ApplicationController in engine

View Hints

In parent app use engine_name.path_helper to link into engine

link_to “Store”, depot_engine.root_path

You can override views by putting them in

app/views/engine_name/controller/view_name

Rake Tasks

Rake tasks can be added in lib/tasks

Show up in parent application

Can be run in rails engine via app namespace

Other Stuff

Custom Rails Generators

Injecting routes into the parent

Config options

Initializers

etc. etc.

Exstatic - Authorization

Uses a config option to call an authentication method

Setup in initializer

spec/controllers/pages_controller_spec.rb

Exstatic - Generators

Used for migrations but no longer needed

You can however setup a rails_engine:install to automate setup

Exstatic - Dynamic RoutesCan add routes directly into parent app

lib/exstatic/engine.rb

Can also ensure you aren’t overwriting a route that is defined by parent

lib/exstatic/validators/nonexistant_path_validator.rb

Resources

http://edgeguides.rubyonrails.org/engines.html

http://keithschacht.com/creating-a-rails-3-engine-plugin-gem/

http://coding.smashingmagazine.com/2011/06/23/a-guide-to-starting-your-own-rails-engine-gem/

http://viget.com/extend/rails-engine-testing-with-rspec-capybara-and-factorygirl

Gems I “borrowed” from

Devise

https://github.com/plataformatec/devise

High Voltage

https://github.com/thoughtbot/high_voltage