javascript_include_tag

Returns an HTML script tag for each of the sources provided.

Sources may be paths to JavaScript files. Relative paths are assumed to be relative to public/javascripts, full paths are assumed to be relative to the document root. Relative paths are idiomatic, use absolute paths only when needed.

When passing paths, the “.js” extension is optional.

If the application is not using the asset pipeline, to include the default JavaScript expansion pass :defaults as source. By default, :defaults loads jQuery, and that can be overridden in config/application.rb:

config.action_view.javascript_expansions[:defaults] = %w(foo.js bar.js)

When using :defaults or :all, if an application.js file exists in public/javascripts it will be included as well at the end.

You can modify the HTML attributes of the script tag by passing a hash as the last argument.

Examples

javascript_include_tag "xmlhr"
# => <script type="text/javascript" src="/javascripts/xmlhr.js?1284139606"></script>

javascript_include_tag "xmlhr.js"
# => <script type="text/javascript" src="/javascripts/xmlhr.js?1284139606"></script>

javascript_include_tag "common.javascript", "/elsewhere/cools"
# => <script type="text/javascript" src="/javascripts/common.javascript?1284139606"></script>
#    <script type="text/javascript" src="/elsewhere/cools.js?1423139606"></script>

javascript_include_tag "http://www.example.com/xmlhr"
# => <script type="text/javascript" src="http://www.example.com/xmlhr"></script>

javascript_include_tag "http://www.example.com/xmlhr.js"
# => <script type="text/javascript" src="http://www.example.com/xmlhr.js"></script>

javascript_include_tag :defaults
# => <script type="text/javascript" src="/javascripts/jquery.js?1284139606"></script>
#    <script type="text/javascript" src="/javascripts/rails.js?1284139606"></script>
#    <script type="text/javascript" src="/javascripts/application.js?1284139606"></script>

Note: The application.js file is only referenced if it exists

You can also include all JavaScripts in the javascripts directory using :all as the source:

javascript_include_tag :all
# => <script type="text/javascript" src="/javascripts/jquery.js?1284139606"></script>
#    <script type="text/javascript" src="/javascripts/rails.js?1284139606"></script>
#    <script type="text/javascript" src="/javascripts/shop.js?1284139606"></script>
#    <script type="text/javascript" src="/javascripts/checkout.js?1284139606"></script>
#    <script type="text/javascript" src="/javascripts/application.js?1284139606"></script>

Note that your defaults of choice will be included first, so they will be available to all subsequently included files.

If you want Rails to search in all the subdirectories under public/javascripts, you should explicitly set :recursive:

javascript_include_tag :all, :recursive => true

Caching multiple JavaScripts into one

You can also cache multiple JavaScripts into one file, which requires less HTTP connections to download and can better be compressed by gzip (leading to faster transfers). Caching will only happen if config.perform_caching is set to true (which is the case by default for the Rails production environment, but not for the development environment).

Examples

# assuming config.perform_caching is false
javascript_include_tag :all, :cache => true
# => <script type="text/javascript" src="/javascripts/jquery.js?1284139606"></script>
#    <script type="text/javascript" src="/javascripts/rails.js?1284139606"></script>
#    <script type="text/javascript" src="/javascripts/shop.js?1284139606"></script>
#    <script type="text/javascript" src="/javascripts/checkout.js?1284139606"></script>
#    <script type="text/javascript" src="/javascripts/application.js?1284139606"></script>

# assuming config.perform_caching is true
javascript_include_tag :all, :cache => true
# => <script type="text/javascript" src="/javascripts/all.js?1344139789"></script>

# assuming config.perform_caching is false
javascript_include_tag "jquery", "cart", "checkout", :cache => "shop"
# => <script type="text/javascript" src="/javascripts/jquery.js?1284139606"></script>
#    <script type="text/javascript" src="/javascripts/cart.js?1289139157"></script>
#    <script type="text/javascript" src="/javascripts/checkout.js?1299139816"></script>

# assuming config.perform_caching is true
javascript_include_tag "jquery", "cart", "checkout", :cache => "shop"
# => <script type="text/javascript" src="/javascripts/shop.js?1299139816"></script>

The :recursive option is also available for caching:

javascript_include_tag :all, :cache => true, :recursive => true

# File actionpack/lib/action_view/helpers/asset_tag_helpers/javascript_tag_helpers.rb, line 186
        def javascript_include_tag(*sources)
          @javascript_include ||= JavascriptIncludeTag.new(config, asset_paths)
          @javascript_include.include_tag(*sources)
        end