Permalink
Browse files

Update layouts and rendering guide javascript_include_tag to bring it…

… in line with Rails 3.1
  • Loading branch information...
radar committed Dec 3, 2011
1 parent baa93a1 commit d7c2fcd856e7a592955598d5ae3f2216cd5abcff
Showing with 42 additions and 5 deletions.
  1. +42 −5 railties/guides/source/layouts_and_rendering.textile
@@ -671,19 +671,33 @@ There are three tag options available for the +auto_discovery_link_tag+:
h5. Linking to JavaScript Files with the +javascript_include_tag+ h5. Linking to JavaScript Files with the +javascript_include_tag+
The +javascript_include_tag+ helper returns an HTML +script+ tag for each source provided. Rails looks in +public/javascripts+ for these files by default, but you can specify a full path relative to the document root, or a URL, if you prefer. For example, to include +public/javascripts/main.js+: The +javascript_include_tag+ helper returns an HTML +script+ tag for each source provided.
If you are using Rails with the "Asset Pipeline":http://guides.rubyonrails.org/asset_pipeline.html enabled, this helper will generate a link to +/assets/javascripts/+ rather than +public/javascripts+ which was used in earlier versions of Rails. This link is then served by the Sprockets gem, which was introduced in Rails 3.1.
A JavaScript file within a Rails application or Rails engine goes in one of three locations: +app/assets+, +lib/assets+ or +vendor/assets+. These locations are explained in detail in the "Asset Organisation section in the Asset Pipeline Guide":http://guides.rubyonrails.org/asset_pipeline.html#asset-organization
You can specify a full path relative to the document root, or a URL, if you prefer. For example, to link to a JavaScript file that is inside a directory called +javascripts+ inside of one of +app/assets+, +lib/assets+ or +vendor/assets+, you would do this:
<erb> <erb>
<%= javascript_include_tag "main" %> <%= javascript_include_tag "main" %>
</erb> </erb>
To include +public/javascripts/main.js+ and +public/javascripts/columns.js+: Rails will then output a +script+ tag such as this:
<html>
<script src='/assets/main.js' type="text/javascript"></script>
</html>
The request to this asset is then served by the Sprockets gem.
To include multiple files such as +app/assets/javascripts/main.js+ and +app/assets/javascripts/columns.js+ at the same time:
<erb> <erb>
<%= javascript_include_tag "main", "columns" %> <%= javascript_include_tag "main", "columns" %>
</erb> </erb>
To include +public/javascripts/main.js+ and +public/photos/columns.js+: To include +app/assets/javascripts/main.js+ and +app/assets/javascripts/photos/columns.js+:
<erb> <erb>
<%= javascript_include_tag "main", "/photos/columns" %> <%= javascript_include_tag "main", "/photos/columns" %>
@@ -701,15 +715,38 @@ If the application does not use the asset pipeline, the +:defaults+ option loads
<%= javascript_include_tag :defaults %> <%= javascript_include_tag :defaults %>
</erb> </erb>
And you can in any case override the expansion in <tt>config/application.rb</tt>: Outputting +script+ tags such as this:
<html>
<script src="/javascripts/jquery.js" type="text/javascript"></script>
<script src="/javascripts/jquery_ujs.js" type="text/javascript"></script>
</html>
These two files for jQuery, +jquery.js+ and +jquery_ujs.js+ must be placed inside +public/javascripts+ if the application doesn't use the asset pipeline. These files can be downloaded from the "jquery-rails repository on GitHub":https://github.com/indirect/jquery-rails/tree/master/vendor/assets/javascripts
WARNING: If you are using the Asset Pipeline, this tag will render a +script+ tag for an asset called +defaults.js+, which would not exist in your application unless you've explicitly defined it to be.
And you can in any case override the +:defaults+ expansion in <tt>config/application.rb</tt>:
<ruby> <ruby>
config.action_view.javascript_expansions[:defaults] = %w(foo.js bar.js) config.action_view.javascript_expansions[:defaults] = %w(foo.js bar.js)
</ruby> </ruby>
You can also define new defaults:
<ruby>
config.action_view.javascript_expansions[:projects] = %w(projects.js tickets.js)
</ruby>
And use them by referencing them exactly like +:defaults+:
<erb>
<%= javascript_include_tag :projects %>
</erb>
When using <tt>:defaults</tt>, if an <tt>application.js</tt> file exists in <tt>public/javascripts</tt> it will be included as well at then end. When using <tt>:defaults</tt>, if an <tt>application.js</tt> file exists in <tt>public/javascripts</tt> it will be included as well at then end.
Also, the +:all+ option loads every JavaScript file in +public/javascripts+: Also, if the Asset Pipeline is disabled, the +:all+ expansion loads every JavaScript file in +public/javascripts+:
<erb> <erb>
<%= javascript_include_tag :all %> <%= javascript_include_tag :all %>

0 comments on commit d7c2fcd

Please sign in to comment.