Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 613 lines (561 sloc) 21.716 kB
b17e358 @josevalim Move configuration to subfolders.
josevalim authored
1 require 'rails/railtie'
812136a @jeremy Fix unstated usage of Pathname
jeremy authored
2 require 'active_support/core_ext/module/delegation'
3 require 'pathname'
53c13f1 @anildigital Use Config::CONFIG['host_os'] instead of RUBY_PLATFORM [#4477 state:r…
anildigital authored
4 require 'rbconfig'
c787bfd @drogus Engine can now load its own plugins
drogus authored
5 require 'rails/engine/railties'
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
6
7 module Rails
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
8 # Rails::Engine allows you to wrap a specific Rails application and share it across
9 # different applications. Since Rails 3.0, every <tt>Rails::Application</tt> is nothing
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
10 # more than an engine, allowing you to share it very easily.
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
11 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
12 # Any <tt>Rails::Engine</tt> is also a <tt>Rails::Railtie</tt>, so the same methods
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
13 # (like <tt>rake_tasks</tt> and +generators+) and configuration available in the
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
14 # latter can also be used in the former.
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
15 #
16 # == Creating an Engine
17 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
18 # In Rails versions prior to 3.0, your gems automatically behaved as engines, however,
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
19 # this coupled Rails to Rubygems. Since Rails 3.0, if you want a gem to automatically
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
20 # behave as an engine, you have to specify an +Engine+ for it somewhere inside
21 # your plugin's +lib+ folder (similar to how we specify a +Railtie+):
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
22 #
23 # # lib/my_engine.rb
24 # module MyEngine
25 # class Engine < Rails::Engine
26 # end
27 # end
28 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
29 # Then ensure that this file is loaded at the top of your <tt>config/application.rb</tt>
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
30 # (or in your +Gemfile+) and it will automatically load models, controllers and helpers
31 # inside +app+, load routes at <tt>config/routes.rb</tt>, load locales at
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
32 # <tt>config/locales/*</tt>, and load tasks at <tt>lib/tasks/*</tt>.
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
33 #
34 # == Configuration
35 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
36 # Besides the +Railtie+ configuration which is shared across the application, in a
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
37 # <tt>Rails::Engine</tt> you can access <tt>autoload_paths</tt>, <tt>eager_load_paths</tt>
38 # and <tt>autoload_once_paths</tt>, which, differently from a <tt>Railtie</tt>, are scoped to
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
39 # the current engine.
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
40 #
41 # Example:
42 #
43 # class MyEngine < Rails::Engine
44 # # Add a load path for this specific Engine
6f83a50 @fxn renames load_(once_)paths to autoload_(once_)paths in dependencies an…
fxn authored
45 # config.autoload_paths << File.expand_path("../lib/some/path", __FILE__)
4bacc2a @josevalim Update the documentation for Engine and Railtie.
josevalim authored
46 #
47 # initializer "my_engine.add_middleware" do |app|
20f0e9f @jeremy Fix docs typo: app.middlewares -> app.middleware
jeremy authored
48 # app.middleware.use MyEngine::Middleware
4bacc2a @josevalim Update the documentation for Engine and Railtie.
josevalim authored
49 # end
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
50 # end
9cfeefb @wycats Reorganized initializers a bit to enable better hooks for common case…
wycats authored
51 #
adfd43a @drogus Add documentation on app_generators
drogus authored
52 # == Generators
53 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
54 # You can set up generators for engines with <tt>config.generators</tt> method:
adfd43a @drogus Add documentation on app_generators
drogus authored
55 #
56 # class MyEngine < Rails::Engine
57 # config.generators do |g|
58 # g.orm :active_record
59 # g.template_engine :erb
60 # g.test_framework :test_unit
61 # end
62 # end
63 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
64 # You can also set generators for an application by using <tt>config.app_generators</tt>:
adfd43a @drogus Add documentation on app_generators
drogus authored
65 #
66 # class MyEngine < Rails::Engine
67 # # note that you can also pass block to app_generators in the same way you
68 # # can pass it to generators method
69 # config.app_generators.orm :datamapper
70 # end
71 #
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
72 # == Paths
73 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
74 # Since Rails 3.0, both your application and engines do not have hardcoded paths.
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
75 # This means that you are not required to place your controllers at <tt>app/controllers</tt>,
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
76 # but in any place which you find convenient.
77 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
78 # For example, let's suppose you want to place your controllers in <tt>lib/controllers</tt>.
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
79 # All you would need to do is:
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
80 #
81 # class MyEngine < Rails::Engine
a8b1780 @josevalim Updated DOCS for engines and added a couple TODOs. Also, commented in…
josevalim authored
82 # paths["app/controllers"] = "lib/controllers"
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
83 # end
84 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
85 # You can also have your controllers loaded from both <tt>app/controllers</tt> and
86 # <tt>lib/controllers</tt>:
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
87 #
88 # class MyEngine < Rails::Engine
a8b1780 @josevalim Updated DOCS for engines and added a couple TODOs. Also, commented in…
josevalim authored
89 # paths["app/controllers"] << "lib/controllers"
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
90 # end
91 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
92 # The available paths in an engine are:
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
93 #
94 # class MyEngine < Rails::Engine
d649bf1 @josevalim Provide a cleaner syntax for paths configuration that does not rely o…
josevalim authored
95 # paths["app"] #=> ["app"]
96 # paths["app/controllers"] #=> ["app/controllers"]
97 # paths["app/helpers"] #=> ["app/helpers"]
98 # paths["app/models"] #=> ["app/models"]
99 # paths["app/views"] #=> ["app/views"]
100 # paths["lib"] #=> ["lib"]
101 # paths["lib/tasks"] #=> ["lib/tasks"]
102 # paths["config"] #=> ["config"]
103 # paths["config/initializers"] #=> ["config/initializers"]
104 # paths["config/locales"] #=> ["config/locales"]
105 # paths["config/routes"] #=> ["config/routes.rb"]
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
106 # end
107 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
108 # Your <tt>Application</tt> class adds a couple more paths to this set. And as in your
109 # <tt>Application</tt>,all folders under +app+ are automatically added to the load path.
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
110 # So if you have <tt>app/observers</tt>, it's added by default.
781d0a9 @josevalim Add docs for Railtie, Engine, Plugin and Application.
josevalim authored
111 #
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
112 # == Endpoint
113 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
114 # An engine can be also a rack application. It can be useful if you have a rack application that
115 # you would like to wrap with +Engine+ and provide some of the +Engine+'s features.
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
116 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
117 # To do that, use the +endpoint+ method:
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
118 #
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
119 # module MyEngine
120 # class Engine < Rails::Engine
121 # endpoint MyRackApplication
122 # end
123 # end
124 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
125 # Now you can mount your engine in application's routes just like that:
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
126 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
127 # MyRailsApp::Application.routes.draw do
128 # mount MyEngine::Engine => "/engine"
129 # end
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
130 #
131 # == Middleware stack
132 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
133 # As an engine can now be rack endpoint, it can also have a middleware stack. The usage is exactly
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
134 # the same as in <tt>Application</tt>:
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
135 #
136 # module MyEngine
137 # class Engine < Rails::Engine
138 # middleware.use SomeMiddleware
139 # end
140 # end
141 #
142 # == Routes
143 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
144 # If you don't specify an endpoint, routes will be used as the default endpoint. You can use them
145 # just like you use an application's routes:
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
146 #
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
147 # # ENGINE/config/routes.rb
148 # MyEngine::Engine.routes.draw do
149 # match "/" => "posts#index"
150 # end
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
151 #
152 # == Mount priority
153 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
154 # Note that now there can be more than one router in your application, and it's better to avoid
155 # passing requests through many routers. Consider this situation:
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
156 #
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
157 # MyRailsApp::Application.routes.draw do
158 # mount MyEngine::Engine => "/blog"
159 # match "/blog/omg" => "main#omg"
160 # end
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
161 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
162 # +MyEngine+ is mounted at <tt>/blog</tt>, and <tt>/blog/omg</tt> points to application's
163 # controller. In such a situation, requests to <tt>/blog/omg</tt> will go through +MyEngine+,
164 # and if there is no such route in +Engine+'s routes, it will be dispatched to <tt>main#omg</tt>.
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
165 # It's much better to swap that:
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
166 #
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
167 # MyRailsApp::Application.routes.draw do
168 # match "/blog/omg" => "main#omg"
169 # mount MyEngine::Engine => "/blog"
170 # end
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
171 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
172 # Now, +Engine+ will get only requests that were not handled by +Application+.
153df92 @drogus Added documentation on endpoint, middeware stack and routes for Engine
drogus authored
173 #
a132229 @drogus Added ability to set asset_path for engines
drogus authored
174 # == Asset path
175 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
176 # When you use +Engine+ with its own public directory, you will probably want to copy or symlink it
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
177 # to application's public directory. To simplify generating paths for assets, you can set <tt>asset_path</tt>
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
178 # for an engine:
a132229 @drogus Added ability to set asset_path for engines
drogus authored
179 #
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
180 # module MyEngine
181 # class Engine < Rails::Engine
182 # config.asset_path = "/my_engine/%s"
183 # end
2e4e1e7 @drogus Added documentation for namespaced Engine
drogus authored
184 # end
a132229 @drogus Added ability to set asset_path for engines
drogus authored
185 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
186 # With such a config, asset paths will be automatically modified inside +Engine+:
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
187 #
188 # image_path("foo.jpg") #=> "/my_engine/images/foo.jpg"
a132229 @drogus Added ability to set asset_path for engines
drogus authored
189 #
32157a2 @drogus Add documentation on serving assets from engine strategies
drogus authored
190 # == Serving static files
191 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
192 # By default, Rails uses <tt>ActionDispatch::Static</tt> to serve static files in development mode. This is ok
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
193 # while you develop your application, but when you want to deploy it, assets from an engine will not be
a8b1780 @josevalim Updated DOCS for engines and added a couple TODOs. Also, commented in…
josevalim authored
194 # served by default. You should choose one of the two following strategies:
32157a2 @drogus Add documentation on serving assets from engine strategies
drogus authored
195 #
196 # * enable serving static files by setting config.serve_static_assets to true
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
197 # * copy engine's public files to application's public folder with <tt>rake ENGINE_NAME:install:assets</tt>, for example
198 # <tt>rake my_engine:install:assets</tt>
32157a2 @drogus Add documentation on serving assets from engine strategies
drogus authored
199 #
1a161c7 @drogus Document engine_name
drogus authored
200 # == Engine name
201 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
202 # There are some places where an Engine's name is used:
203 # * routes: when you mount an Engine with <tt>mount(MyEngine::Engine => '/my_engine')</tt>,
204 # it's used as default :as option
205 # * some of the rake tasks are based on engine name, e.g. <tt>my_engine:install:migrations</tt>,
206 # <tt>my_engine:install:assets</tt>
1a161c7 @drogus Document engine_name
drogus authored
207 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
208 # Engine name is set by default based on class name. For <tt>MyEngine::Engine</tt> it will be
209 # <tt>my_engine_engine</tt>. You can change it manually it manually using the <tt>engine_name</tt> method:
1a161c7 @drogus Document engine_name
drogus authored
210 #
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
211 # module MyEngine
212 # class Engine < Rails::Engine
213 # engine_name "my_engine"
214 # end
1a161c7 @drogus Document engine_name
drogus authored
215 # end
216 #
8e955c5 @drogus Should be isolated engine instead of namespaced engine
drogus authored
217 # == Isolated Engine
2e4e1e7 @drogus Added documentation for namespaced Engine
drogus authored
218 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
219 # Normally when you create controllers, helpers and models inside an engine, they are treated
220 # as they were created inside the application. This means all application helpers and named routes
221 # will be available to your engine's controllers.
a8b1780 @josevalim Updated DOCS for engines and added a couple TODOs. Also, commented in…
josevalim authored
222 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
223 # However, sometimes you want to isolate your engine from the application, especially if your engine
224 # has its own router. To do that, you simply need to call +isolate_namespace+. This method requires
a8b1780 @josevalim Updated DOCS for engines and added a couple TODOs. Also, commented in…
josevalim authored
225 # you to pass a module where all your controllers, helpers and models should be nested to:
2e4e1e7 @drogus Added documentation for namespaced Engine
drogus authored
226 #
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
227 # module MyEngine
228 # class Engine < Rails::Engine
5d5eb2b @drogus Rename namespace method to isolate_namespace.
drogus authored
229 # isolate_namespace MyEngine
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
230 # end
2e4e1e7 @drogus Added documentation for namespaced Engine
drogus authored
231 # end
232 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
233 # With such an engine, everything that is inside the +MyEngine+ module will be isolated from
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
234 # the application.
2e4e1e7 @drogus Added documentation for namespaced Engine
drogus authored
235 #
236 # Consider such controller:
237 #
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
238 # module MyEngine
239 # class FooController < ActionController::Base
240 # end
2e4e1e7 @drogus Added documentation for namespaced Engine
drogus authored
241 # end
242 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
243 # If an engine is marked as isolated, +FooController+ has access only to helpers from +Engine+ and
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
244 # <tt>url_helpers</tt> from <tt>MyEngine::Engine.routes</tt>.
2e4e1e7 @drogus Added documentation for namespaced Engine
drogus authored
245 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
246 # The next thing that changes in isolated engines is the behaviour of routes. Normally, when you namespace
247 # your controllers, you also need to do namespace all your routes. With an isolated engine,
a8b1780 @josevalim Updated DOCS for engines and added a couple TODOs. Also, commented in…
josevalim authored
248 # the namespace is applied by default, so you can ignore it in routes:
249 #
250 # MyEngine::Engine.routes.draw do
251 # resources :articles
252 # end
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
253 #
254 # The routes above will automatically point to <tt>MyEngine::ApplicationContoller</tt>. Furthermore, you don't
737abe4 @rtlechow Railties typos.
rtlechow authored
255 # need to use longer url helpers like <tt>my_engine_articles_path</tt>. Instead, you should simply use
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
256 # <tt>articles_path</tt> as you would do with your application.
257 #
258 # To make that behaviour consistent with other parts of the framework, an isolated engine also has influence on
259 # <tt>ActiveModel::Naming</tt>. When you use a namespaced model, like <tt>MyEngine::Article</tt>, it will normally
737abe4 @rtlechow Railties typos.
rtlechow authored
260 # use the prefix "my_engine". In an isolated engine, the prefix will be omitted in url helpers and
a8b1780 @josevalim Updated DOCS for engines and added a couple TODOs. Also, commented in…
josevalim authored
261 # form fields for convenience.
07411ca @drogus List all of isolated engine changes
drogus authored
262 #
263 # polymorphic_url(MyEngine::Article.new) #=> "articles_path"
264 #
265 # form_for(MyEngine::Article.new) do
266 # text_field :title #=> <input type="text" name="article[title]" id="article_title" />
267 # end
268 #
737abe4 @rtlechow Railties typos.
rtlechow authored
269 # Additionally isolated engine will set its name according to namespace, so
a8b1780 @josevalim Updated DOCS for engines and added a couple TODOs. Also, commented in…
josevalim authored
270 # MyEngine::Engine.engine_name #=> "my_engine". It will also set MyEngine.table_name_prefix
271 # to "my_engine_", changing MyEngine::Article model to use my_engine_article table.
2e4e1e7 @drogus Added documentation for namespaced Engine
drogus authored
272 #
434139f @drogus Documented mounted helpers
drogus authored
273 # == Using Engine's routes outside Engine
274 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
275 # Since you can now mount an engine inside application's routes, you do not have direct access to +Engine+'s
276 # <tt>url_helpers</tt> inside +Application+. When you mount an engine in an application's routes, a special helper is
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
277 # created to allow you to do that. Consider such a scenario:
434139f @drogus Documented mounted helpers
drogus authored
278 #
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
279 # # APP/config/routes.rb
280 # MyApplication::Application.routes.draw do
281 # mount MyEngine::Engine => "/my_engine", :as => "my_engine"
282 # match "/foo" => "foo#index"
283 # end
434139f @drogus Documented mounted helpers
drogus authored
284 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
285 # Now, you can use the <tt>my_engine</tt> helper inside your application:
434139f @drogus Documented mounted helpers
drogus authored
286 #
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
287 # class FooController < ApplicationController
288 # def index
289 # my_engine.root_url #=> /my_engine/
290 # end
434139f @drogus Documented mounted helpers
drogus authored
291 # end
292 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
293 # There is also a <tt>main_app</tt> helper that gives you access to application's routes inside Engine:
434139f @drogus Documented mounted helpers
drogus authored
294 #
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
295 # module MyEngine
296 # class BarController
a8b1780 @josevalim Updated DOCS for engines and added a couple TODOs. Also, commented in…
josevalim authored
297 # def index
298 # main_app.foo_path #=> /foo
299 # end
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
300 # end
434139f @drogus Documented mounted helpers
drogus authored
301 # end
302 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
303 # Note that the <tt>:as</tt> option given to mount takes the <tt>engine_name</tT> as default, so most of the time
304 # you can simply omit it.
34cd8a6 @drogus Add some more docs on polymorphic_url with routes proxy
drogus authored
305 #
2373eed @techpeace Make all references to engines lowercase in docs.
techpeace authored
306 # Finally, if you want to generate a url to an engine's route using <tt>polymorphic_url</tt>, you also need
a8b1780 @josevalim Updated DOCS for engines and added a couple TODOs. Also, commented in…
josevalim authored
307 # to pass the engine helper. Let's say that you want to create a form pointing to one of the
308 # engine's routes. All you need to do is pass the helper as the first element in array with
309 # attributes for url:
34cd8a6 @drogus Add some more docs on polymorphic_url with routes proxy
drogus authored
310 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
311 # form_for([my_engine, @user])
34cd8a6 @drogus Add some more docs on polymorphic_url with routes proxy
drogus authored
312 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
313 # This code will use <tt>my_engine.user_path(@user)</tt> to generate the proper route.
34cd8a6 @drogus Add some more docs on polymorphic_url with routes proxy
drogus authored
314 #
dfac9b1 @drogus Strengthen documantation on engine's migrations and seed data
drogus authored
315 # == Migrations & seed data
316 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
317 # Engines can have their own migrations. The default path for migrations is exactly the same
318 # as in application: <tt>db/migrate</tt>
dfac9b1 @drogus Strengthen documantation on engine's migrations and seed data
drogus authored
319 #
320 # To use engine's migrations in application you can use rake task, which copies them to
321 # application's dir:
322 #
a8b1780 @josevalim Updated DOCS for engines and added a couple TODOs. Also, commented in…
josevalim authored
323 # rake ENGINE_NAME:install:migrations
dfac9b1 @drogus Strengthen documantation on engine's migrations and seed data
drogus authored
324 #
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
325 # Note that some of the migrations may be skipped if a migration with the same name already exists
326 # in application. In such a situation you must decide whether to leave that migration or rename the
a2c52f1 @drogus Update documentation for new tasks
drogus authored
327 # migration in application and rerun copying migrations.
328 #
dfac9b1 @drogus Strengthen documantation on engine's migrations and seed data
drogus authored
329 # If your engine has migrations, you may also want to prepare data for the database in
5f5e3b7 @techpeace Copy-edit and format Rails::Engine docs.
techpeace authored
330 # the <tt>seeds.rb</tt> file. You can load that data using the <tt>load_seed</tt> method, e.g.
dfac9b1 @drogus Strengthen documantation on engine's migrations and seed data
drogus authored
331 #
332 # MyEngine::Engine.load_seed
333 #
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
334 class Engine < Railtie
b17e358 @josevalim Move configuration to subfolders.
josevalim authored
335 autoload :Configuration, "rails/engine/configuration"
37d3266 @josevalim Add missing autoload.
josevalim authored
336 autoload :Railties, "rails/engine/railties"
788fce2 @josevalim Create configurable modules and ensure that they are added only on di…
josevalim authored
337
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
338 class << self
5d5eb2b @drogus Rename namespace method to isolate_namespace.
drogus authored
339 attr_accessor :called_from, :isolated
ef4afed @drogus There is no need to make isolated? method with bang-bang, just alias …
drogus authored
340 alias :isolated? :isolated
2068b8c @drogus Added tests for railtie_name and aliased it in engine as engine_name
drogus authored
341 alias :engine_name :railtie_name
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
342
343 def inherited(base)
f5ee855 @josevalim Improve heuristic for railties default name, otherwise railties may b…
josevalim authored
344 unless base.abstract_railtie?
788fce2 @josevalim Create configurable modules and ensure that they are added only on di…
josevalim authored
345 base.called_from = begin
a5684df @josevalim Ensure config.after_initializer is executed before building the middl…
josevalim authored
346 # Remove the line number from backtraces making sure we don't leave anything behind
4bfe30c @spastorino delete from :number until the end
spastorino authored
347 call_stack = caller.map { |p| p.sub(/:\d+.*/, '') }
21ff884 @fxn in regexps, the dot in a character class is not a metacharacter
fxn authored
348 File.dirname(call_stack.detect { |p| p !~ %r[railties[\w.-]*/lib/rails|rack[\w.-]*/lib/rack] })
788fce2 @josevalim Create configurable modules and ensure that they are added only on di…
josevalim authored
349 end
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
350 end
788fce2 @josevalim Create configurable modules and ensure that they are added only on di…
josevalim authored
351
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
352 super
353 end
354
3939d6b @drogus Removed ActionDispatch::Static, but left empty MiddlewareStack to uni…
drogus authored
355 def endpoint(endpoint = nil)
356 @endpoint = endpoint if endpoint
357 @endpoint
358 end
c7664d1 @drogus Include application's helpers and router helpers by default, but incl…
drogus authored
359
5d5eb2b @drogus Rename namespace method to isolate_namespace.
drogus authored
360 def isolate_namespace(mod)
db8a864 @drogus Add table_name_prefix to Engine's namespace automatically
drogus authored
361 engine_name(generate_railtie_name(mod))
362
0a28073 Engines that use isolate_namespace with nested modules should set cor…
Rolf Timmermans authored
363 self.routes.default_scope = { :module => ActiveSupport::Inflector.underscore(mod.name) }
5d5eb2b @drogus Rename namespace method to isolate_namespace.
drogus authored
364 self.isolated = true
74598fe @drogus Do not overwrite _railtie method on namespace while creating isolated…
drogus authored
365
366 unless mod.respond_to?(:_railtie)
0a28073 Engines that use isolate_namespace with nested modules should set cor…
Rolf Timmermans authored
367 name = engine_name
74598fe @drogus Do not overwrite _railtie method on namespace while creating isolated…
drogus authored
368 _railtie = self
369 mod.singleton_class.instance_eval do
370 define_method(:_railtie) do
371 _railtie
372 end
373
f821055 @drogus Do not create table_name_prefix method on isolated module if the meth…
drogus authored
374 unless mod.respond_to?(:table_name_prefix)
375 define_method(:table_name_prefix) do
376 "#{name}_"
377 end
74598fe @drogus Do not overwrite _railtie method on namespace while creating isolated…
drogus authored
378 end
379 end
380 end
e35c204 @drogus Include all helpers from non-namespaced engines
drogus authored
381 end
051127d @drogus Rails::Engine.find(path) - method to find engine by path
drogus authored
382
383 # Finds engine with given path
384 def find(path)
c7cfdd0 @dcrec1 refactored Engine.#find by giving an explicit name to a variable and …
dcrec1 authored
385 expanded_path = File.expand_path path.to_s
386 Rails::Engine::Railties.engines.find { |engine|
387 File.expand_path(engine.root.to_s) == expanded_path
1db4969 @tenderlove only compute path.to_s once
tenderlove authored
388 }
051127d @drogus Rails::Engine.find(path) - method to find engine by path
drogus authored
389 end
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
390 end
391
32a5b49 @drogus Move singleton pattern to Railtie and remove Engine::Configurable and…
drogus authored
392 delegate :middleware, :root, :paths, :to => :config
5d5eb2b @drogus Rename namespace method to isolate_namespace.
drogus authored
393 delegate :engine_name, :isolated?, :to => "self.class"
2b75b94 @josevalim Plugin is now an Engine.
josevalim authored
394
395 def load_tasks
7317d9e @josh Remove implicit controller namespacing from new dsl
josh authored
396 super
d649bf1 @josevalim Provide a cleaner syntax for paths configuration that does not rely o…
josevalim authored
397 paths["lib/tasks"].existent.sort.each { |ext| load(ext) }
2b75b94 @josevalim Plugin is now an Engine.
josevalim authored
398 end
399
351816f @josevalim Ensure that eager_load actually takes place just after the middleware…
josevalim authored
400 def eager_load!
401 config.eager_load_paths.each do |load_path|
402 matcher = /\A#{Regexp.escape(load_path)}\/(.*)\.rb\Z/
403 Dir.glob("#{load_path}/**/*.rb").sort.each do |file|
404 require_dependency file.sub(matcher, '\1')
405 end
406 end
407 end
408
c787bfd @drogus Engine can now load its own plugins
drogus authored
409 def railties
32a5b49 @drogus Move singleton pattern to Railtie and remove Engine::Configurable and…
drogus authored
410 @railties ||= self.class::Railties.new(config)
c787bfd @drogus Engine can now load its own plugins
drogus authored
411 end
412
ad6be08 @drogus Made Engine valid rack app with its own middleware stack
drogus authored
413 def app
092b148 @drogus Engine can now serve files with ActionDispatch::Static
drogus authored
414 @app ||= begin
415 config.middleware = config.middleware.merge_into(default_middleware_stack)
416 config.middleware.build(endpoint)
417 end
ad6be08 @drogus Made Engine valid rack app with its own middleware stack
drogus authored
418 end
419
420 def endpoint
c989d1a @drogus Engine sets routes as default rack endpoint if no endpoint was given
drogus authored
421 self.class.endpoint || routes
ad6be08 @drogus Made Engine valid rack app with its own middleware stack
drogus authored
422 end
423
424 def call(env)
a132229 @drogus Added ability to set asset_path for engines
drogus authored
425 app.call(env.merge!(env_config))
426 end
427
428 def env_config
429 @env_config ||= {
430 'action_dispatch.routes' => routes,
431 'action_dispatch.asset_path' => config.asset_path
432 }
ad6be08 @drogus Made Engine valid rack app with its own middleware stack
drogus authored
433 end
434
08f4713 @drogus Refactored routes reloading to use RouteSet#append instead keeping bl…
drogus authored
435 def routes
c989d1a @drogus Engine sets routes as default rack endpoint if no endpoint was given
drogus authored
436 @routes ||= ActionDispatch::Routing::RouteSet.new
08f4713 @drogus Refactored routes reloading to use RouteSet#append instead keeping bl…
drogus authored
437 @routes.append(&Proc.new) if block_given?
ec5d846 @drogus Properly reload routes defined in class definition
drogus authored
438 @routes
c989d1a @drogus Engine sets routes as default rack endpoint if no endpoint was given
drogus authored
439 end
440
675f3ea @drogus Gather initializers from railties in engines to get rid of additional…
drogus authored
441 def initializers
442 initializers = []
443 railties.all { |r| initializers += r.initializers }
444 initializers += super
445 initializers
446 end
447
32a5b49 @drogus Move singleton pattern to Railtie and remove Engine::Configurable and…
drogus authored
448 def config
937f419 @drogus Engine's assets are now served with ActionDispatch::Static
drogus authored
449 @config ||= Engine::Configuration.new(find_root_with_flag("lib"))
32a5b49 @drogus Move singleton pattern to Railtie and remove Engine::Configurable and…
drogus authored
450 end
451
d475de7 @drogus Add helper for loading seed data for engine and application
drogus authored
452 # Load data from db/seeds.rb file. It can be used in to load engines'
453 # seeds, e.g.:
454 #
455 # Blog::Engine.load_seed
456 def load_seed
d649bf1 @josevalim Provide a cleaner syntax for paths configuration that does not rely o…
josevalim authored
457 seed_file = paths["db/seeds"].existent.first
d475de7 @drogus Add helper for loading seed data for engine and application
drogus authored
458 load(seed_file) if File.exist?(seed_file)
459 end
460
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
461 # Add configured load paths to ruby load paths and remove duplicates.
9cfeefb @wycats Reorganized initializers a bit to enable better hooks for common case…
wycats authored
462 initializer :set_load_path, :before => :bootstrap_hook do
9b19a6f @josevalim A few changes were done in this commit:
josevalim authored
463 _all_load_paths.reverse_each do |path|
4ae7936 @josevalim Got tests working once again.
josevalim authored
464 $LOAD_PATH.unshift(path) if File.directory?(path)
465 end
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
466 $LOAD_PATH.uniq!
467 end
468
469 # Set the paths from which Rails will automatically load source files,
470 # and the load_once paths.
9cfeefb @wycats Reorganized initializers a bit to enable better hooks for common case…
wycats authored
471 #
472 # This needs to be an initializer, since it needs to run once
473 # per engine and get the engine as a block parameter
474 initializer :set_autoload_paths, :before => :bootstrap_hook do |app|
9b19a6f @josevalim A few changes were done in this commit:
josevalim authored
475 ActiveSupport::Dependencies.autoload_paths.unshift(*_all_autoload_paths)
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
476 ActiveSupport::Dependencies.autoload_once_paths.unshift(*_all_autoload_once_paths)
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
477
98240c4 @josevalim Get rid of initializers global and create i18n railtie.
josevalim authored
478 # Freeze so future modifications will fail rather than do nothing mysteriously
6f83a50 @fxn renames load_(once_)paths to autoload_(once_)paths in dependencies an…
fxn authored
479 config.autoload_paths.freeze
9b19a6f @josevalim A few changes were done in this commit:
josevalim authored
480 config.eager_load_paths.freeze
6f83a50 @fxn renames load_(once_)paths to autoload_(once_)paths in dependencies an…
fxn authored
481 config.autoload_once_paths.freeze
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
482 end
483
226d8e7 @josevalim Refactor MetalLoader and RoutesReloader to rely less on class configu…
josevalim authored
484 initializer :add_routing_paths do |app|
d649bf1 @josevalim Provide a cleaner syntax for paths configuration that does not rely o…
josevalim authored
485 paths = self.paths["config/routes"].existent
486
487 if routes? || paths.any?
488 app.routes_reloader.paths.unshift(*paths)
08f4713 @drogus Refactored routes reloading to use RouteSet#append instead keeping bl…
drogus authored
489 app.routes_reloader.route_sets << routes
98240c4 @josevalim Get rid of initializers global and create i18n railtie.
josevalim authored
490 end
491 end
492
1177a40 @josevalim Fix i18n locales order test.
josevalim authored
493 # I18n load paths are a special case since the ones added
494 # later have higher priority.
98240c4 @josevalim Get rid of initializers global and create i18n railtie.
josevalim authored
495 initializer :add_locales do
d649bf1 @josevalim Provide a cleaner syntax for paths configuration that does not rely o…
josevalim authored
496 config.i18n.railties_load_path.concat(paths["config/locales"].existent)
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
497 end
498
02c5137 @josevalim Add view paths to Engine setup.
josevalim authored
499 initializer :add_view_paths do
d649bf1 @josevalim Provide a cleaner syntax for paths configuration that does not rely o…
josevalim authored
500 views = paths["app/views"].existent
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
501 unless views.empty?
502 ActiveSupport.on_load(:action_controller){ prepend_view_path(views) }
503 ActiveSupport.on_load(:action_mailer){ prepend_view_path(views) }
4aded43 @wycats Replace the placeholder base_hook API with on_load. To specify some c…
wycats authored
504 end
02c5137 @josevalim Add view paths to Engine setup.
josevalim authored
505 end
506
7cccfed @drogus Allow Engines loading its own environment file from config/environments
drogus authored
507 initializer :load_environment_config, :before => :load_environment_hook do
d649bf1 @josevalim Provide a cleaner syntax for paths configuration that does not rely o…
josevalim authored
508 environment = paths["config/environments"].existent.first
7cccfed @drogus Allow Engines loading its own environment file from config/environments
drogus authored
509 require environment if environment
510 end
511
a5e509d @drogus We should avoid creating additional initializers when we can, adding …
drogus authored
512 initializer :append_asset_paths do
1860d87 @josevalim Ensure asset_path defaults to nil for application
josevalim authored
513 config.asset_path ||= default_asset_path
8284fd3 @drogus Get rid of static_paths method and instead configure paths for Action…
drogus authored
514
d649bf1 @josevalim Provide a cleaner syntax for paths configuration that does not rely o…
josevalim authored
515 public_path = paths["public"].first
8284fd3 @drogus Get rid of static_paths method and instead configure paths for Action…
drogus authored
516 if config.compiled_asset_path && File.exist?(public_path)
517 config.static_asset_paths[config.compiled_asset_path] = public_path
518 end
519 end
e35c204 @drogus Include all helpers from non-namespaced engines
drogus authored
520
2fe70c1 @josevalim Booya, sprockets now works from Engines.
josevalim authored
521 initializer :append_app_assets_path do |app|
522 app.config.assets.paths.unshift *paths["vendor/assets"].existent
523 app.config.assets.paths.unshift *paths["app/assets"].existent
524 end
525
d649bf1 @josevalim Provide a cleaner syntax for paths configuration that does not rely o…
josevalim authored
526 initializer :prepend_helpers_path do |app|
5d5eb2b @drogus Rename namespace method to isolate_namespace.
drogus authored
527 if !isolated? || (app == self)
d649bf1 @josevalim Provide a cleaner syntax for paths configuration that does not rely o…
josevalim authored
528 app.config.helpers_paths.unshift(*paths["app/helpers"].existent)
e35c204 @drogus Include all helpers from non-namespaced engines
drogus authored
529 end
530 end
531
9af189a @drogus I've changed that test along the way, it should actually stay without…
drogus authored
532 initializer :load_config_initializers do
d649bf1 @josevalim Provide a cleaner syntax for paths configuration that does not rely o…
josevalim authored
533 config.paths["config/initializers"].existent.sort.each do |initializer|
9af189a @drogus I've changed that test along the way, it should actually stay without…
drogus authored
534 load(initializer)
535 end
536 end
537
b43b686 @drogus engines_blank_point should always be the last initializer in Engine
drogus authored
538 initializer :engines_blank_point do
539 # We need this initializer so all extra initializers added in engines are
540 # consistently executed after all the initializers above across all engines.
541 end
542
a9bf91e @drogus Add 'foo:install:migrations' task to copy migrations from foo engine
drogus authored
543 rake_tasks do
544 next if self.is_a?(Rails::Application)
545
546 namespace railtie_name do
43215de @drogus Add task foo:install (where foo is plugin) as a shortcutinstall:migra…
drogus authored
547 desc "Shortcut for running both rake #{railtie_name}:install:migrations and #{railtie_name}:install:assets"
548 task :install do
549 Rake::Task["#{railtie_name}:install:migrations"].invoke
550 Rake::Task["#{railtie_name}:install:assets"].invoke
551 end
552
a9bf91e @drogus Add 'foo:install:migrations' task to copy migrations from foo engine
drogus authored
553 namespace :install do
a8b1780 @josevalim Updated DOCS for engines and added a couple TODOs. Also, commented in…
josevalim authored
554 # TODO Add assets copying to this list
555 # TODO Skip this if there is no paths["db/migrate"] for the engine
a9bf91e @drogus Add 'foo:install:migrations' task to copy migrations from foo engine
drogus authored
556 desc "Copy migrations from #{railtie_name} to application"
557 task :migrations do
558 ENV["FROM"] = railtie_name
559 Rake::Task["railties:install:migrations"].invoke
560 end
f07cbec @drogus Do not treat information about skipped migrations as WARNINGs but as …
drogus authored
561
959f857 @drogus Added foo:install:assets task that copies assets from plugins public …
drogus authored
562 desc "Copy assets from #{railtie_name} to application"
563 task :assets do
564 ENV["FROM"] = railtie_name
565 Rake::Task["railties:install:assets"].invoke
566 end
f07cbec @drogus Do not treat information about skipped migrations as WARNINGs but as …
drogus authored
567 end
a9bf91e @drogus Add 'foo:install:migrations' task to copy migrations from foo engine
drogus authored
568 end
569 end
570
788fce2 @josevalim Create configurable modules and ensure that they are added only on di…
josevalim authored
571 protected
1860d87 @josevalim Ensure asset_path defaults to nil for application
josevalim authored
572
573 def default_asset_path
574 "/#{railtie_name}%s"
575 end
576
d649bf1 @josevalim Provide a cleaner syntax for paths configuration that does not rely o…
josevalim authored
577 def routes?
578 defined?(@routes)
579 end
580
32a5b49 @drogus Move singleton pattern to Railtie and remove Engine::Configurable and…
drogus authored
581 def find_root_with_flag(flag, default=nil)
582 root_path = self.class.called_from
583
584 while root_path && File.directory?(root_path) && !File.exist?("#{root_path}/#{flag}")
585 parent = File.dirname(root_path)
586 root_path = parent != root_path && parent
587 end
588
589 root = File.exist?("#{root_path}/#{flag}") ? root_path : default
590 raise "Could not find root path for #{self}" unless root
591
4a4ff14 @josevalim Use RbConfig instead of Config for 1.9.3 compatibility.
josevalim authored
592 RbConfig::CONFIG['host_os'] =~ /mswin|mingw/ ?
32a5b49 @drogus Move singleton pattern to Railtie and remove Engine::Configurable and…
drogus authored
593 Pathname.new(root).expand_path : Pathname.new(root).realpath
594 end
595
3939d6b @drogus Removed ActionDispatch::Static, but left empty MiddlewareStack to uni…
drogus authored
596 def default_middleware_stack
597 ActionDispatch::MiddlewareStack.new
598 end
788fce2 @josevalim Create configurable modules and ensure that they are added only on di…
josevalim authored
599
6f194bb @josevalim Small tidy up on Rails::Engine.
josevalim authored
600 def _all_autoload_once_paths
601 config.autoload_once_paths
602 end
603
9b19a6f @josevalim A few changes were done in this commit:
josevalim authored
604 def _all_autoload_paths
605 @_all_autoload_paths ||= (config.autoload_paths + config.eager_load_paths + config.autoload_once_paths).uniq
606 end
607
608 def _all_load_paths
609 @_all_load_paths ||= (config.paths.load_paths + _all_autoload_paths).uniq
788fce2 @josevalim Create configurable modules and ensure that they are added only on di…
josevalim authored
610 end
7fcf859 @josevalim Massive cleanup in Railties and load stack.
josevalim authored
611 end
6324eee @jeremy plugin rails/init.rb deprecation message
jeremy authored
612 end
Something went wrong with that request. Please try again.