From 849e546bc98ca39fdf4edfe85a4e72327b155486 Mon Sep 17 00:00:00 2001 From: Claudi Martinez Date: Thu, 29 Oct 2015 08:54:45 +0100 Subject: Added warning on coding engine controllers --- guides/source/engines.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'guides/source') diff --git a/guides/source/engines.md b/guides/source/engines.md index f961b799f1..7f6021a5eb 100644 --- a/guides/source/engines.md +++ b/guides/source/engines.md @@ -239,6 +239,24 @@ 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: + +```ruby +# articles_controller.rb: +require_dependency "blorgh/application_controller" # Explicit dependency required! +module Blorgh + class ArticlesController < ApplicationController + ... + end +end +``` + 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 From 86030f24e95ef75859a4e89fc8da785ef14e1ff6 Mon Sep 17 00:00:00 2001 From: Claudi Martinez Date: Thu, 29 Oct 2015 08:56:50 +0100 Subject: Fixed typo --- guides/source/engines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'guides/source') diff --git a/guides/source/engines.md b/guides/source/engines.md index 7f6021a5eb..ccbda7c712 100644 --- a/guides/source/engines.md +++ b/guides/source/engines.md @@ -243,7 +243,7 @@ WARNING: Due to the way Rails autoloads controllers, it could happen that the ma 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 +`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: -- cgit v1.2.3 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/source') 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 From 2ae24ddc31e706b0a7f5360cebe0e5c996eb6de4 Mon Sep 17 00:00:00 2001 From: Claudi Martinez Date: Fri, 13 Nov 2015 09:18:04 +0100 Subject: Improved explanation --- guides/source/engines.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'guides/source') diff --git a/guides/source/engines.md b/guides/source/engines.md index e670962fe6..359796b1ff 100644 --- a/guides/source/engines.md +++ b/guides/source/engines.md @@ -241,10 +241,7 @@ applications into engines. 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 +not your engine's application controller. Ruby is able to resolve the `ApplicationController` constant, and therefore the autoloading mechanism is not triggered. See the section [When Constants Aren't Missed](autoloading_and_reloading_constants.html#when-constants-aren-t-missed) of the [Autoloading and Reloading Constants](autoloading_and_reloading_constants.html) guide for further details. 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: -- cgit v1.2.3