Skip to content

Commit

Permalink
Few improvements to the engines guide
Browse files Browse the repository at this point in the history
* Fix a few typos

* Gather the paragraphs that mention the namespacing that happens
  inside an engine's folder structure.

[ci skip]
  • Loading branch information
robin850 committed Jun 14, 2020
1 parent b6a9d3a commit d5bae0f
Showing 1 changed file with 10 additions and 27 deletions.
37 changes: 10 additions & 27 deletions guides/source/engines.md
Expand Up @@ -112,7 +112,7 @@ that provides the following:

The `--mountable` option will add to the `--full` option:

* Asset manifest files (`application.js` and `application.css`)
* Asset manifest files (`blorgh_manifest.js` and `application.css`)
* A namespaced `ApplicationController` stub
* A namespaced `ApplicationHelper` stub
* A layout view template for the engine
Expand Down Expand Up @@ -207,8 +207,8 @@ instead be namespaced and called `Blorgh::Article`. In addition, the table for t
model is namespaced, becoming `blorgh_articles`, rather than simply `articles`.
Similar to the model namespacing, a controller called `ArticlesController` becomes
`Blorgh::ArticlesController` and the views for that controller will not be at
`app/views/articles`, but `app/views/blorgh/articles` instead. Mailers are namespaced
as well.
`app/views/articles`, but `app/views/blorgh/articles` instead. Mailers, jobs
and helpers are namespaced as well.

Finally, routes will also be isolated within the engine. This is one of the most
important parts about namespacing, and is discussed later in the
Expand Down Expand Up @@ -259,29 +259,12 @@ WARNING: Don't use `require` because it will break the automatic reloading of cl
in the development environment - using `require_dependency` ensures that classes are
loaded and unloaded in the correct manner.

Within the `app/helpers` directory there is a `blorgh` directory that
contains a file called `application_helper.rb`. This file will provide any
common functionality for the helpers of the engine. The `blorgh` directory
is where the other helpers for the engine will go. By placing them within
this namespaced directory, you prevent them from possibly clashing with
identically-named route helpers within other engines or even within the
application.

Within the `app/jobs` directory there is a `blorgh` directory that
contains a file called `application_job.rb`. This file will provide any
common functionality for the jobs of the engine. The `blorgh` directory
is where the other jobs for the engine will go. By placing them within
this namespaced directory, you prevent them from possibly clashing with
identically-named jobs within other engines or even within the
application.

Within the `app/mailers` directory there is a `blorgh` directory that
contains a file called `application_mailer.rb`. This file will provide any
common functionality for the mailers of the engine. The `blorgh` directory
is where the other mailers for the engine will go. By placing them within
this namespaced directory, you prevent them from possibly clashing with
identically-named mailers within other engines or even within the
application.
Just like for `app/controllers`, you will find a `blorgh` subdirectory under
the `app/helpers`, `app/jobs`, `app/mailers` and `app/models` directories
containing the associated `application_*.rb` file for gathering common
functionalities. By placing your files under this subdirectory and namespacing
your objects, you prevent them from possibly clashing with identically-named
elements within other engines or even within the application.

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
Expand Down Expand Up @@ -1344,7 +1327,7 @@ which case the application's asset would take precedence and the engine's one
would be ignored.

Imagine that you did have an asset located at
`app/assets/stylesheets/blorgh/style.css` To include this asset inside an
`app/assets/stylesheets/blorgh/style.css`. To include this asset inside an
application, just use `stylesheet_link_tag` and reference the asset as if it
were inside the engine:

Expand Down

0 comments on commit d5bae0f

Please sign in to comment.