From 1ba6b406981892f3501bc6a345573fd861641f9a Mon Sep 17 00:00:00 2001 From: Ryan Bigg Date: Thu, 6 Oct 2011 08:40:36 +1100 Subject: [engines] Expanded 'What are engines?' and 'Generating an engine' sections --- railties/guides/source/engines.textile | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) (limited to 'railties') diff --git a/railties/guides/source/engines.textile b/railties/guides/source/engines.textile index dc87ac4095..83672fd66c 100644 --- a/railties/guides/source/engines.textile +++ b/railties/guides/source/engines.textile @@ -12,11 +12,30 @@ endprologue. h3. What are engines? -Engines can be considered miniature applications that provide functionality to their host applications. A Rails application is actually just a "supercharged" engine, with the `Rails::Application` class inheriting from `Rails::Engine`. Therefore, engines and applications share common functionality but are at the same time two separate beasts. +Engines can be considered miniature applications that provide functionality to their host applications. A Rails application is actually just a "supercharged" engine, with the +Rails::Application+ class inheriting from +Rails::Engine+. Therefore, engines and applications share common functionality but are at the same time two separate beasts. Engines and applications also share a common structure, as you'll see later in this guide. + +Engines are also closely related to plugins where the two share a common +lib+ directory structure and are both generated using the +rails plugin new+ generator. + +The engine that will be generated for this guide will be called "blorgh". The engine will provide blogging functionality to its host applications, allowing for new posts and comments to be created. For now, you will be working solely within the engine itself and in later sections you'll see how to hook it into an application. + +Engines can also be isolated from their host applications. This means that an application is able to have a path provided by a routing helper such as +posts_path+ and use an engine also that provides a path also called +posts_path+, and the two would not clash. Along with this, controllers, models and table names are also namespaced. You'll see how to do this later in this guide. + +To see demonstrations of other engines, check out "Devise":https://github.com/plataformatec/devise, an engine that provides authentication for its parent applications, or "Forem":https://github.com/radar/forem, an engine that provides forum functionality. h3. Generating an engine -TODO: The engine that will be generated for this guide will be called "blorgh". It's a blogging engine that provides posts and comments and that's it. +To generate an engine with Rails 3.1, you will need to run the plugin generator and pass it the +--mountable+ option. To generate the beginnings of the "blorgh" engine you will need to run this command in a terminal: + + +$ rails plugin new blorgh --mountable + + +The +--mountable+ option tells the plugin generator that you want to create an engine (which is a mountable plugin, hence the option name), creating the basic directory structure of an engine by providing things such as the foundations of an +app+ folder, as well a +config/routes.rb+ file. This generator also provides a file at +lib/blorgh/engine.rb+ which is identical in function to an application's +config/application.rb+ file. + +Inside the +app+ directory there lives the standard +assets+, +controllers+, +helpers+, +mailers+, +models+ and +views+ directories that you should be familiar with from an application. + +Within the +app/controllers+ directory there is a +blorgh+ directory and inside that a file called +application_controller.rb+. This file will provide any common functionality for the controllers of the engine. The +blorgh+ directory is where the other controllers for the engine will go. By placing them within this namespaced directory, you prevent them from possibly clashing with identically-named controllers within other engines or even within the application. + TODO: Describe here the process of generating an engine and what an engine comes with. -- cgit v1.2.3 From 876d3f23d2370790623c6ef261d7c2366fb404d3 Mon Sep 17 00:00:00 2001 From: Ryan Bigg Date: Thu, 6 Oct 2011 08:47:06 +1100 Subject: [engines guide] More explanation for 'Generating an engine' --- railties/guides/source/engines.textile | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) (limited to 'railties') diff --git a/railties/guides/source/engines.textile b/railties/guides/source/engines.textile index 83672fd66c..ddd2e50a6c 100644 --- a/railties/guides/source/engines.textile +++ b/railties/guides/source/engines.textile @@ -34,10 +34,28 @@ The +--mountable+ option tells the plugin generator that you want to create an e Inside the +app+ directory there lives the standard +assets+, +controllers+, +helpers+, +mailers+, +models+ and +views+ directories that you should be familiar with from an application. -Within the +app/controllers+ directory there is a +blorgh+ directory and inside that a file called +application_controller.rb+. This file will provide any common functionality for the controllers of the engine. The +blorgh+ directory is where the other controllers for the engine will go. By placing them within this namespaced directory, you prevent them from possibly clashing with identically-named controllers within other engines or even within the application. +At the root of the engine's directory, lives a +blorgh.gemspec+ file. When you include the engine into the application later on, you will do so with this line in a Rails application's +Gemfile+: + + + gem 'blorgh', :path => "vendor/engines/blorgh" + + +By specifying it as a gem within the +Gemfile+, Bundler will load it as such, parsing this +blorgh.gemspec+ file and requiring a file within the +lib+ directory called +lib/blorgh.rb+. This file requires the +blorgh/engine.rb+ file (located at +lib/blorgh/engine.rb+) and defines a base module called +Blorgh+. + + +require "blorgh/engine" +module Blorgh +end + -TODO: Describe here the process of generating an engine and what an engine comes with. +Within +lib/blorgh/engine.rb+ is the base class for the engine: + + + TODO: lib/blorgh/engine.rb + + +Within the +app/controllers+ directory there is a +blorgh+ directory and inside that a file called +application_controller.rb+. This file will provide any common functionality for the controllers of the engine. The +blorgh+ directory is where the other controllers for the engine will go. By placing them within this namespaced directory, you prevent them from possibly clashing with identically-named controllers within other engines or even within the application. h3. Providing engine functionality -- cgit v1.2.3 From 3d595c5eaeec43e5dc9f2930420506108b0ce813 Mon Sep 17 00:00:00 2001 From: Nick Quaranto Date: Wed, 5 Oct 2011 22:27:33 -0400 Subject: use Rails.root.join for assets guide --- railties/guides/source/asset_pipeline.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index 7795b297f3..ccbc737f17 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -120,7 +120,7 @@ All subdirectories that exist within these three locations are added to the sear You can add additional (fully qualified) paths to the pipeline in +config/application.rb+. For example: -config.assets.paths << "#{Rails.root}/app/assets/flash" +config.assets.paths << Rails.root.join("app", "assets", "flash") h4. Coding Links to Assets -- cgit v1.2.3 From 00751f02576719291822685bc97214af49887161 Mon Sep 17 00:00:00 2001 From: Ryan Bigg Date: Thu, 6 Oct 2011 13:32:21 +1100 Subject: [config guide] mention that to_prepare hooks are called upon every request in dev, but only once in production --- railties/guides/source/configuring.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties') diff --git a/railties/guides/source/configuring.textile b/railties/guides/source/configuring.textile index ce1d759d5b..e56932c26c 100644 --- a/railties/guides/source/configuring.textile +++ b/railties/guides/source/configuring.textile @@ -461,7 +461,7 @@ Rails has 5 initialization events which can be hooked into (listed in the order * +before_initialize+: This is run directly before the initialization process of the application occurs with the +:bootstrap_hook+ initializer near the beginning of the Rails initialization process. -* +to_prepare+: Run after the initializers are ran for all Railties (including the application itself), but before eager loading and the middleware stack is built. +* +to_prepare+: Run after the initializers are ran for all Railties (including the application itself), but before eager loading and the middleware stack is built. More importantly, will run upon every request in +development+, but only once (during boot-up) in +production+ and +test+. * +before_eager_load+: This is run directly before eager loading occurs, which is the default behaviour for the _production_ environment and not for the +development+ environment. -- cgit v1.2.3 From 02eac2db9407ddebaca26ea6cb26d6d64a7fb24b Mon Sep 17 00:00:00 2001 From: Ryan Bigg Date: Thu, 6 Oct 2011 13:32:39 +1100 Subject: [config guide] Show example of defining initialization hooks --- railties/guides/source/configuring.textile | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'railties') diff --git a/railties/guides/source/configuring.textile b/railties/guides/source/configuring.textile index e56932c26c..baf944cf8d 100644 --- a/railties/guides/source/configuring.textile +++ b/railties/guides/source/configuring.textile @@ -467,6 +467,25 @@ Rails has 5 initialization events which can be hooked into (listed in the order * +after_initialize+: Run directly after the initialization of the application, but before the application initializers are run. +To define an event for these hooks, use the block syntax within a +Rails::Aplication+, +Rails::Railtie+ or +Rails::Engine+ subclass: + + +module YourApp + class Application < Rails::Application + config.before_initialize do + # initialization code goes here + end + end +end + + +Alternatively, you can also do it through the +config+ method on the +Rails.application+ object: + + +Rails.application.config.before_initialize do + # initialization code goes here +end + WARNING: Some parts of your application, notably observers and routing, are not yet set up at the point where the +after_initialize+ block is called. -- cgit v1.2.3 From 79a719a6d27ad8f7782a8586392fc9716927c850 Mon Sep 17 00:00:00 2001 From: Hendy Tanata Date: Thu, 6 Oct 2011 14:03:46 +0800 Subject: Grammar fixes for the routing guide. --- railties/guides/source/routing.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties') diff --git a/railties/guides/source/routing.textile b/railties/guides/source/routing.textile index bf18402b60..f281009fee 100644 --- a/railties/guides/source/routing.textile +++ b/railties/guides/source/routing.textile @@ -596,7 +596,7 @@ match "/stories/:name" => redirect {|params| "/posts/#{params[:name].pluralize}" match "/stories" => redirect {|p, req| "/posts/#{req.subdomain}" } -Please note that this redirection is a 301 "Moved Permanently" redirect. Keep in mind that some web browser or proxy server will cache this type of redirect, make the old page inaccessible. +Please note that this redirection is a 301 "Moved Permanently" redirect. Keep in mind that some web browsers or proxy servers will cache this type of redirect, making the old page inaccessible. In all of these cases, if you don't provide the leading host (+http://www.example.com+), Rails will take those details from the current request. -- cgit v1.2.3 From 545ddbdbc5b61716fb884488206567a130902f0a Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Thu, 6 Oct 2011 23:50:16 +0530 Subject: fix an example --- railties/guides/source/caching_with_rails.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties') diff --git a/railties/guides/source/caching_with_rails.textile b/railties/guides/source/caching_with_rails.textile index 19378d63ce..4273d0dd64 100644 --- a/railties/guides/source/caching_with_rails.textile +++ b/railties/guides/source/caching_with_rails.textile @@ -188,7 +188,7 @@ end You may notice that the actual product gets passed to the sweeper, so if we were caching the edit action for each product, we could add an expire method which specifies the page we want to expire: - expire_action(:controller => 'products', :action => 'edit', :id => product) +expire_action(:controller => 'products', :action => 'edit', :id => product.id) Then we add it to our controller to tell it to call the sweeper when certain actions are called. So, if we wanted to expire the cached content for the list and edit actions when the create action was called, we could do the following: -- cgit v1.2.3