Skip to content
This repository
Browse code

Added documentation for namespaced Engine

  • Loading branch information...
commit 2e4e1e7d0ce9bd0e9ea116a05a4ffcd989541cbd 1 parent db8a864
Piotr Sarnacki authored August 03, 2010

Showing 1 changed file with 34 additions and 2 deletions. Show diff stats Hide diff stats

  1. 36  railties/lib/rails/engine.rb
36  railties/lib/rails/engine.rb
@@ -153,13 +153,45 @@ module Rails
153 153
   # to application's public directory. To simplify generating paths for assets, you can set asset_path
154 154
   # for an Engine:
155 155
   #
156  
-  # class MyEngine::Engine < Rails::Engine
157  
-  #   config.asset_path = "/my_engine/%s"
  156
+  # module MyEngine
  157
+  #   class Engine < Rails::Engine
  158
+  #     config.asset_path = "/my_engine/%s"
  159
+  #   end
158 160
   # end
159 161
   #
160 162
   # With such config, asset paths will be automatically modified inside Engine:
161 163
   # image_path("foo.jpg") #=> "/my_engine/images/foo.jpg"
162 164
   #
  165
+  # == Namespaced Engine
  166
+  #
  167
+  # Normally, when you create controllers, helpers and models inside engine, they are treated
  168
+  # as they would be created inside application. One of the cosequences of that is including
  169
+  # application's helpers and url_helpers inside controller. Sometimes, especially when your
  170
+  # engine provides its own routes, you don't want that. To isolate engine's stuff from application
  171
+  # you can use namespace method:
  172
+  #
  173
+  # module MyEngine
  174
+  #   class Engine < Rails::Engine
  175
+  #     namespace MyEngine
  176
+  #   end
  177
+  # end
  178
+  #
  179
+  # With such Engine, everything that is inside MyEngine module, will be isolated from application.
  180
+  #
  181
+  # Consider such controller:
  182
+  #
  183
+  # module MyEngine
  184
+  #   class FooController < ActionController::Base
  185
+  #   end
  186
+  # end
  187
+  #
  188
+  # If engine is marked as namespaced, FooController has access only to helpers from engine and
  189
+  # url_helpers from MyEngine::Engine.routes.
  190
+  #
  191
+  # Additionaly namespaced engine will set its name according to namespace, so in that case:
  192
+  # MyEngine::Engine.engine_name #=> "my_engine"
  193
+  # and it will set MyEngine.table_name_prefix to "my_engine_"
  194
+  #
163 195
   class Engine < Railtie
164 196
     autoload :Configurable,  "rails/engine/configurable"
165 197
     autoload :Configuration, "rails/engine/configuration"

0 notes on commit 2e4e1e7

Please sign in to comment.
Something went wrong with that request. Please try again.