From ef202f6b7d86adde84a7193bc5066b447054b76d Mon Sep 17 00:00:00 2001
From: Claudi Martinez <claudix.kernel@gmail.com>
Date: Sun, 1 Nov 2015 20:52:21 +0100
Subject: Improved explanation
---
guides/source/engines.md | 26 ++++++++++++++++----------
1 file changed, 16 insertions(+), 10 deletions(-)
diff --git a/guides/source/engines.md b/guides/source/engines.md
index ccbda7c712..e670962fe6 100644
--- a/guides/source/engines.md
+++ b/guides/source/engines.md
@@ -239,17 +239,19 @@ NOTE: The `ApplicationController` class inside an engine is named just like a
Rails application in order to make it easier for you to convert your
applications into engines.
-WARNING: Due to the way Rails autoloads controllers, it could happen that the main
-application's `ApplicationController` were loaded before the engine's `ApplicationController`.
-In such case, the Ruby interpreter would not load the latter class and your engine's
-controllers would miss methods defined in it (because they would inherit from main
-`ApplicationController`). For this reason the code in engine's controllers must explicitly
-tell Ruby they depend on the right application controller. This can be achieved with
-a single line at the top of the controllers files. For example:
+NOTE: Because of the way that Ruby does constant lookup you may run into a situation
+where your engine controller is inheriting from the main application controller and
+not your engine's application controller. Ruby will look in the ancestor chain for
+constants and every class has `Object` as an ancestor, meaning that if the global
+`ApplicationController` is loaded Ruby will return that and not call `const_missing`
+and trigger the Rails autoloading mechanism. The best way to prevent this from
+happening is to use `require_dependency` to ensure that the engine's application
+controller is loaded. For example:
+
+``` ruby
+# app/controllers/blorgh/articles_controller.rb:
+require_dependency "blorgh/application_controller"
-```ruby
-# articles_controller.rb:
-require_dependency "blorgh/application_controller" # Explicit dependency required!
module Blorgh
class ArticlesController < ApplicationController
...
@@ -257,6 +259,10 @@ module Blorgh
end
```
+WARNING: Don't use `require` because it will break the automatic reloading of classes
+in the development environment - using `require_dependency` ensures that classes are
+loaded and unloaded in the correct manner.
+
Lastly, the `app/views` directory contains a `layouts` folder, which contains a
file at `blorgh/application.html.erb`. This file allows you to specify a layout
for the engine. If this engine is to be used as a stand-alone engine, then you
--
cgit v1.2.3