Skip to content
This repository
Browse code

Added documentation on endpoint, middeware stack and routes for Engine

  • Loading branch information...
commit 153df92f9f670055505dd91c429b010478fac9d6 1 parent ccd422f
Piotr Sarnacki authored July 22, 2010

Showing 1 changed file with 60 additions and 0 deletions. Show diff stats Hide diff stats

  1. 60  railties/lib/rails/engine.rb
60  railties/lib/rails/engine.rb
@@ -87,6 +87,66 @@ module Rails
87 87
   # all folders under "app" are automatically added to the load path. So if you have
88 88
   # "app/observers", it's added by default.
89 89
   #
  90
+  # == Endpoint
  91
+  #
  92
+  # Engine can be also a rack application. It can be useful if you have a rack application that
  93
+  # you would like to wrap with Engine and provide some of the Engine's features.
  94
+  #
  95
+  # To do that, use endpoint method:
  96
+  #   module MyEngine
  97
+  #     class Engine < Rails::Engine
  98
+  #       endpoint MyRackApplication
  99
+  #     end
  100
+  #   end
  101
+  #
  102
+  # Now you can mount your engine in application's routes just like that:
  103
+  #
  104
+  # MyRailsApp::Application.routes.draw do
  105
+  #   mount MyEngine::Engine => "/engine"
  106
+  # end
  107
+  #
  108
+  # == Middleware stack
  109
+  #
  110
+  # As Engine can now be rack endpoint, it can also have a middleware stack. The usage is exactly
  111
+  # the same as in application:
  112
+  #
  113
+  #   module MyEngine
  114
+  #     class Engine < Rails::Engine
  115
+  #       middleware.use SomeMiddleware
  116
+  #     end
  117
+  #   end
  118
+  #
  119
+  # == Routes
  120
+  #
  121
+  # If you don't specify endpoint, routes will be used as default endpoint. You can use them
  122
+  # just like you use application's routes:
  123
+  #
  124
+  # # ENGINE/config/routes.rb
  125
+  # MyEngine::Engine.routes.draw do
  126
+  #   match "/" => "posts#index"
  127
+  # end
  128
+  #
  129
+  # == Mount priority
  130
+  #
  131
+  # Note that now there can be more than one router in you application and it's better to avoid
  132
+  # passing requests through many routers. Consider such situation:
  133
+  #
  134
+  # MyRailsApp::Application.routes.draw do
  135
+  #   mount MyEngine::Engine => "/blog"
  136
+  #   match "/blog/omg" => "main#omg"
  137
+  # end
  138
+  #
  139
+  # MyEngine is mounted at "/blog" path and additionaly "/blog/omg" points application's controller.
  140
+  # In such situation request to "/blog/omg" will go through MyEngine and if there is no such route
  141
+  # in Engine's routes, it will be dispatched to "main#omg". It's much better to swap that:
  142
+  #
  143
+  # MyRailsApp::Application.routes.draw do
  144
+  #   match "/blog/omg" => "main#omg"
  145
+  #   mount MyEngine::Engine => "/blog"
  146
+  # end
  147
+  #
  148
+  # Now, Engine will get only requests that were not handled by application.
  149
+  #
90 150
   class Engine < Railtie
91 151
     autoload :Configurable,  "rails/engine/configurable"
92 152
     autoload :Configuration, "rails/engine/configuration"

0 notes on commit 153df92

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