From ef202f6b7d86adde84a7193bc5066b447054b76d Mon Sep 17 00:00:00 2001 From: Claudi Martinez Date: Sun, 1 Nov 2015 20:52:21 +0100 Subject: Improved explanation --- guides/source/engines.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) (limited to 'guides') 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