1. Rails engines in
large apps
Created by /Enrico Teotti @agenteo

2. Start off with a small
application

3. and the app complexity will
grow over time

4. Start off with a big complex
application

5. ignoring complexity will hurt
you

6. In Ruby on Rails that is:

7. too many responsibilities in
active record models

9. long controller methods

11. helpers modules doing a
gazillion things

13. concerns

15. These poor decisions are sometime justified as:
"This is the Rails way!"
"Those are the Rails
conventions!"
"This is what a Rails developer
expect to see!"

16. bullshit

17. Rails gives conventions that fit small application domains but doesn't
have any for larger problems

18. How can Ruby on Rails engines
help?

19. Engines can drop in functionality in your Rails monolithic app
Devise
Kaminari

20. But they can do more that that
"Rails::Engine allows you to wrap a specific Rails application or subset of
functionality and share it with other applications or within a larger
packaged application. Since Rails 3.0, every Rails::Application is just an
engine, which allows for simple feature and application sharing."
Rails API

21. we will create very specific engine only used in this app

22. Domain Model
This is a domain model taken from Evan's book DDD
It is a simplified version of a real live problem

23. use Engines as building bricks
of the application!

24. First, create an integration test
in the main app
spec/features/ship_cargo_spec.rb
require 'spec_helper'
feature 'As a staff member I want to ship a cargo' do
scenario %{
Given I am on the cargo shipping page
When I fill in a customer
And I fill in a origin and destination
Then I want to see an itinerary } do
visit '/ship_cargo'
end
end

25. rspec
F
Failures:
1) As a staff member I want to ship a cargo
Given I am on the cargo shipping page
When I fill in a customer
And I fill in a origin and destination
Then I want to see an itinerary
Failure/Error: visit '/ship_cargo'
ActionController::RoutingError:
No route matches [GET] "/ship_cargo"
# ./spec/features/ship_cargo_spec.rb:10:in `block (2 levels) in <top (required)="">'
Finished in 0.00523 seconds
1 example, 1 failure
</top>

26. Create an engine
rails plugin new cargo_shipping --mountable -T --dummy-path=spec/dummy

27. You can create a nested folder
structure
If you want to be more formal about the separation of
responsibilities between the engines
The engine name will match ubiquitous language you share with
stakeholders
engines/
├── application_layer
├── domain_layer
│ ├── billing
│ ├── customer
│ └── shipping
└── presentation_layer
└── cargo_shipping

28. Main app Gemfile
gem 'cargo_shipping', path: 'engines/presentation_layer/cargo_shipping'

29. Cargo Shipping Engine
structure
engines/presentation_layer/cargo_shipping/
├── Gemfile
├── Gemfile.lock
├── MIT-LICENSE
├── README.rdoc
├── Rakefile
├── app
│ ├── assets
│ ├── controllers
│ ├── helpers
│ ├── mailers
│ └── views
├── cargo_shipping.gemspec
├── config
│ └── routes.rb
├── lib
│ ├── cargo_shipping
│ ├── cargo_shipping.rb
│ └── tasks
└── spec
└── dummy

30. CargoShipping Engine routes
engines/presentation_layer/cargo_shipping/config/routes.rb
module PresentationLayer
CargoShipping::Engine.routes.draw do
get 'ship_cargo', to: 'ship_cargo#new'
end
end

31. CargoShipping Engine
controller
engines/presentation_layer/cargo_shipping/app/controllers/cargo_shipping/ship_cargo_controller.rb
module CargoShipping
class ShipCargoController < ActionController::Base
def new
end
end
end

32. Run the test again!
F
Failures:
1) As a staff member I want to ship a cargo
Given I am on the cargo shipping page
When I fill in a customer
And I fill in a origin and destination
Then I want to see an itinerary
Failure/Error: visit '/ship_cargo'
ActionController::RoutingError:
No route matches [GET] "/ship_cargo"
# ./spec/features/ship_cargo_spec.rb:10:in `block (2 levels) in <top (required)="">'
Finished in 0.00523 seconds
1 example, 1 failure
</top>

33. We need to change the main
app routes!
config/routes.rb
Maersk::Application.routes.draw do
mount CargoShipping::Engine, at: "/"
end

34. rspec
.
Finished in 0.05205 seconds
1 example, 0 failures

35. CargoShipping Engine
engines/presentation_layer/cargo_shipping/app/controllers/cargo_shipping/ship_cargo_controller.rb
module CargoShipping
class ShipCargoController < ActionController::Base
def new
@customers = Customers::CustomerRepository.all
end
end
end

36. rspec
F
Failures:
1) As a staff member I want to ship a cargo
Given I am on the cargo shipping page
When I fill in a customer
And I fill in a origin and destination
Then I want to see an itinerary
Failure/Error: visit '/ship_cargo'
NameError:
uninitialized constant CargoShipping::ShipCargoController::Customers
# ./engines/presentation_layer/cargo_shipping/app/controllers/cargo_shipping/ship_cargo_controller.r
# ./spec/features/ship_cargo_spec.rb:10:in `block (2 levels) in <top (required)="">'
Finished in 0.04333 seconds
1 example, 1 failure
</top>

37. Create a domain layer engine
rails plugin new customers --mountable -T --dummy-path=spec/dummy

38. Main app Gemfile
gem 'cargo_shipping', path: 'engines/presentation_layer/cargo_shipping'
gem 'customers', path: 'engines/domain_layer/customers'

39. Generating models in
Customers Engine
engines/domain_layer/customers/app/models/customers/customer_repository.rb
rails generate model CustomerRepository email name
invoke active_record
create db/migrate/20130921154844_create_customers_customer_repositories.rb
create app/models/customers/customer_repository.rb
invoke rspec
create spec/models/customers/customer_repository_spec.rb

40. rspec
.
Finished in 0.05205 seconds
1 example, 0 failures

41. Mailing list:
https://groups.google.com/forum/?hl=en#!forum/components-in-rails
References:
Wrangling Large Rails Codebases
Architecting your Rails app for success!
http://pivotallabs.com/leave-your-migrations-in-your-rails-
engines/
http://pivotallabs.com/experience-report-engine-usage-that-
didn-t-work/

42. THE END
Enrico Teotti / @agenteo / teotti.com