Skip to content

Commit

Permalink
Update guides regarding the extension changes
Browse files Browse the repository at this point in the history
With rails/coffee-rails#61 (and #17241), the `.coffee` extension is
favoured over `.js.coffee`. Respectively, with rails/sass-rails#271
`.scss` and `.sass` are favoured over `.css.scss` and `.css.sass`.

Let's update the documentation to reflect that.

[ci skip]
  • Loading branch information
robin850 committed Dec 26, 2014
1 parent 9545041 commit aff03e7
Show file tree
Hide file tree
Showing 3 changed files with 18 additions and 18 deletions.
18 changes: 9 additions & 9 deletions guides/source/asset_pipeline.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,12 +182,12 @@ When you generate a scaffold or a controller, Rails also generates a JavaScript
file (or CoffeeScript file if the `coffee-rails` gem is in the `Gemfile`) and a
Cascading Style Sheet file (or SCSS file if `sass-rails` is in the `Gemfile`)
for that controller. Additionally, when generating a scaffold, Rails generates
the file scaffolds.css (or scaffolds.css.scss if `sass-rails` is in the
the file scaffolds.css (or scaffolds.scss if `sass-rails` is in the
`Gemfile`.)

For example, if you generate a `ProjectsController`, Rails will also add a new
file at `app/assets/javascripts/projects.js.coffee` and another at
`app/assets/stylesheets/projects.css.scss`. By default these files will be ready
file at `app/assets/javascripts/projects.coffee` and another at
`app/assets/stylesheets/projects.scss`. By default these files will be ready
to use by your application immediately using the `require_tree` directive. See
[Manifest Files and Directives](#manifest-files-and-directives) for more details
on require_tree.
Expand Down Expand Up @@ -424,7 +424,7 @@ $('#logo').attr({ src: "<%= asset_path('logo.png') %>" });
This writes the path to the particular asset being referenced.

Similarly, you can use the `asset_path` helper in CoffeeScript files with `erb`
extension (e.g., `application.js.coffee.erb`):
extension (e.g., `application.coffee.erb`):

```js
$('#logo').attr src: "<%= asset_path('logo.png') %>"
Expand Down Expand Up @@ -525,8 +525,8 @@ The file extensions used on an asset determine what preprocessing is applied.
When a controller or a scaffold is generated with the default Rails gemset, a
CoffeeScript file and a SCSS file are generated in place of a regular JavaScript
and CSS file. The example used before was a controller called "projects", which
generated an `app/assets/javascripts/projects.js.coffee` and an
`app/assets/stylesheets/projects.css.scss` file.
generated an `app/assets/javascripts/projects.coffee` and an
`app/assets/stylesheets/projects.scss` file.

In development mode, or if the asset pipeline is disabled, when these files are
requested they are processed by the processors provided by the `coffee-script`
Expand All @@ -538,13 +538,13 @@ web server.
Additional layers of preprocessing can be requested by adding other extensions,
where each extension is processed in a right-to-left manner. These should be
used in the order the processing should be applied. For example, a stylesheet
called `app/assets/stylesheets/projects.css.scss.erb` is first processed as ERB,
called `app/assets/stylesheets/projects.scss.erb` is first processed as ERB,
then SCSS, and finally served as CSS. The same applies to a JavaScript file -
`app/assets/javascripts/projects.js.coffee.erb` is processed as ERB, then
`app/assets/javascripts/projects.coffee.erb` is processed as ERB, then
CoffeeScript, and served as JavaScript.

Keep in mind the order of these preprocessors is important. For example, if
you called your JavaScript file `app/assets/javascripts/projects.js.erb.coffee`
you called your JavaScript file `app/assets/javascripts/projects.erb.coffee`
then it would be processed with the CoffeeScript interpreter first, which
wouldn't understand ERB and therefore you would run into problems.

Expand Down
10 changes: 5 additions & 5 deletions guides/source/command_line.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,9 +153,9 @@ $ bin/rails generate controller Greetings hello
create app/helpers/greetings_helper.rb
invoke assets
invoke coffee
create app/assets/javascripts/greetings.js.coffee
create app/assets/javascripts/greetings.coffee
invoke scss
create app/assets/stylesheets/greetings.css.scss
create app/assets/stylesheets/greetings.scss
```

What all did this generate? It made sure a bunch of directories were in our application, and created a controller file, a view file, a functional test file, a helper for the view, a JavaScript file and a stylesheet file.
Expand Down Expand Up @@ -241,11 +241,11 @@ $ bin/rails generate scaffold HighScore game:string score:integer
create app/views/high_scores/show.json.jbuilder
invoke assets
invoke coffee
create app/assets/javascripts/high_scores.js.coffee
create app/assets/javascripts/high_scores.coffee
invoke scss
create app/assets/stylesheets/high_scores.css.scss
create app/assets/stylesheets/high_scores.scss
invoke scss
identical app/assets/stylesheets/scaffolds.css.scss
identical app/assets/stylesheets/scaffolds.scss
```
The generator checks that there exist the directories for models, controllers, helpers, layouts, functional and unit tests, stylesheets, creates the views, controller, model and database migration for HighScore (creating the `high_scores` table and fields), takes care of the route for the **resource**, and new tests for everything.
Expand Down
8 changes: 4 additions & 4 deletions guides/source/generators.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,11 +199,11 @@ $ bin/rails generate scaffold User name:string
create app/views/users/show.json.jbuilder
invoke assets
invoke coffee
create app/assets/javascripts/users.js.coffee
create app/assets/javascripts/users.coffee
invoke scss
create app/assets/stylesheets/users.css.scss
create app/assets/stylesheets/users.scss
invoke scss
create app/assets/stylesheets/scaffolds.css.scss
create app/assets/stylesheets/scaffolds.scss
```

Looking at this output, it's easy to understand how generators work in Rails 3.0 and above. The scaffold generator doesn't actually generate anything, it just invokes others to do the work. This allows us to add/replace/remove any of those invocations. For instance, the scaffold generator invokes the scaffold_controller generator, which invokes erb, test_unit and helper generators. Since each generator has a single responsibility, they are easy to reuse, avoiding code duplication.
Expand Down Expand Up @@ -409,7 +409,7 @@ $ bin/rails generate scaffold Comment body:text
create app/views/comments/show.json.jbuilder
invoke assets
invoke coffee
create app/assets/javascripts/comments.js.coffee
create app/assets/javascripts/comments.coffee
invoke scss
```
Expand Down

0 comments on commit aff03e7

Please sign in to comment.