Skip to content
This repository
Browse code

syncs assets guide with what's in 3-1-stable

  • Loading branch information...
commit e746c4047cd34accd7f63aa5d09cbb35011c24e2 1 parent 19e8532
Xavier Noria authored
38  railties/guides/source/asset_pipeline.textile
Source Rendered
@@ -15,7 +15,7 @@ h3. What is the Asset Pipeline?
15 15
 
16 16
 The asset pipeline provides a framework to concatenate and minify or compress JavaScript and CSS assets. It also adds the ability to write these assets in other languages such as CoffeeScript, SCSS and ERB.
17 17
 
18  
-Prior to Rails 3.1 these features were added through third-party Ruby libraries such as Jammit and Sprockets. Rails 3.1 includes the +sprockets-rails+ gem, which depends on the +sprockets+ gem, by default.
  18
+Prior to Rails 3.1 these features were added through third-party Ruby libraries such as Jammit and Sprockets. Rails 3.1 is integrated with Sprockets throught ActionPack which depends on the +sprockets+ gem, by default.
19 19
 
20 20
 By having this as a core feature of Rails, all developers can benefit from the power of having their assets pre-processed, compressed and minified by one central library, Sprockets. This is part of Rails' "Fast by default" strategy as outlined by DHH in his 2011 keynote at Railsconf.
21 21
 
@@ -27,6 +27,7 @@ config.assets.enabled = false
27 27
 
28 28
 It is recommended that you use the defaults for all new apps.
29 29
 
  30
+
30 31
 h4. Main Features
31 32
 
32 33
 The first feature of the pipeline is to concatenate assets. This is important in a production environment, as it reduces the number of requests that a browser must make to render a web page. While Rails already has a feature to concatenate these types of assets -- by placing +:cache => true+ at the end of tags such as +javascript_include_tag+ and +stylesheet_link_tag+ -- many people do not use it.
@@ -74,11 +75,14 @@ The other problem is that when static assets are deployed with each new release
74 75
 
75 76
 Fingerprinting avoids all these problems by ensuring filenames are consistent based on their content.
76 77
 
  78
+Fingerprinting is enabled by default for production and disabled for all the others environments. You can enable or disable it in your configuration through the +config.assets.digest+ option.
  79
+
77 80
 More reading:
78 81
 
79 82
 * "Optimize caching":http://code.google.com/speed/page-speed/docs/caching.html
80 83
 * "Revving Filenames: don’t use querystring":http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/
81 84
 
  85
+
82 86
 h3. How to Use the Asset Pipeline
83 87
 
84 88
 In previous versions of Rails, all assets were located in subdirectories of +public+ such as +images+, +javascripts+ and +stylesheets+. With the asset pipeline, the preferred location for these assets is now the +app/assets+ directory. Files in this directory are served by the Sprockets middleware included in the sprockets gem.
@@ -247,14 +251,7 @@ When the +debug_assets+ parameter is set, this line is expanded out into three s
247 251
 
248 252
 This allows the individual parts of an asset to be rendered and debugged separately.
249 253
 
250  
-Additionally if the +config.assets.debug+ is set to true you can debug your assets passing the +:debug+ option to the assets tags:
251  
-
252  
-<erb>
253  
-<%= javascript_include_tag :application, :debug => true %>
254  
-</erb>
255  
-
256  
-
257  
-NOTE. Assets debugging is turned on by default in development and test environments. You can set +config.assets.allow_debugging+ to false to turn it off.
  254
+NOTE. Assets debugging is turned on by default in development and test environments.
258 255
 
259 256
 h3. In Production
260 257
 
@@ -271,7 +268,7 @@ The MD5 is generated from the contents of the compiled files, and is included in
271 268
 
272 269
 Sprockets also sets the +Cache-Control+ HTTP header to +max-age=31536000+. This signals all caches between your server and the client browser that this content (the file served) can be cached for 1 year. The effect of this is to reduce the number of requests for this asset from your server; the asset has a good chance of being in the local browser cache or some intermediate cache.
273 270
 
274  
-This behavior is controlled by the setting of +config.action_controller.perform_caching+ setting in Rails (which is +true+ for production, +false+ for everything else). This value is propagated to Sprockets during initialization for use when action_controller is not available.
  271
+This behavior is controlled by the setting of +config.assets.digest+ setting in Rails (which is +true+ for production, +false+ for everything else).
275 272
 
276 273
 h4. Precompiling Assets
277 274
 
@@ -307,6 +304,20 @@ If you have other manifests or individual stylesheets and JavaScript files to in
307 304
 config.assets.precompile += ['admin.js', 'admin.css', 'swfObject.js']
308 305
 </erb>
309 306
 
  307
+The rake task also generates a +manifest.yml+ that contains a list with all your assets and their fingerprints, using this manifest file the assets helpers avoid hitting to Sprockets to recalculate MD5 hashes for files. Manifest file typically look like this:
  308
+
  309
+<plain>
  310
+---
  311
+rails.png: rails-bd9ad5a560b5a3a7be0808c5cd76a798.png
  312
+jquery-ui.min.js: jquery-ui-7e33882a28fc84ad0e0e47e46cbf901c.min.js
  313
+jquery.min.js: jquery-8a50feed8d29566738ad005e19fe1c2d.min.js
  314
+application.js: application-3fdab497b8fb70d20cfc5495239dfc29.js
  315
+application.css: application-8af74128f904600e41a6e39241464e03.css
  316
+</plain>
  317
+
  318
+The manifest file is generated by default in same folder of your precompiled assets, you can change the location of the file setting the +config.assets.manifest+ option with the full path of the folder where you want save it.
  319
+
  320
+
310 321
 Precompiled assets exist on the filesystem and are served directly by your webserver. They do not have far-future headers by default, so to get the benefit of fingerprinting you'll have to update your server configuration to add them.
311 322
 
312 323
 For Apache:
@@ -325,12 +336,16 @@ For Apache:
325 336
 </LocationMatch>
326 337
 </plain>
327 338
 
328  
-TODO: NGINX instructions
  339
+TODO: nginx instructions
329 340
 
330 341
 When files are precompiled, Sprockets also creates a "Gzip":http://en.wikipedia.org/wiki/Gzip (.gz) version of your assets. This avoids the server having to do this for any requests; it can simply read the compressed files from disc. You must configure your server to use gzip compression and serve the compressed assets that will be stored in the public/assets folder. The following configuration options can be used:
331 342
 
332 343
 TODO: Apache instructions
333 344
 
  345
+TODO: nginx instructions
  346
+
  347
+By default Rails assumes that you have your files precompiled in the production environment, if you want use live compiling (compile your assets during runtime) in production you must set the +config.assets.compile+ to true. You can use this option to fallback to Sprockets when you are using precompiled assets but there are any missing precompiled files. If +config.assets.compile+ option is set to false and there are missing precompiled files you will get an "AssetNoPrecompiledError" indicating the name of the missing file.
  348
+
334 349
 h3. Customizing the Pipeline
335 350
 
336 351
 
@@ -378,6 +393,7 @@ To enable this, pass a +new+ Object to the config option in +application.rb+:
378 393
 config.assets.css_compressor = Transformer.new
379 394
 </erb>
380 395
 
  396
+
381 397
 h4. Changing the _assets_ Path
382 398
 
383 399
 The public path that Sprockets uses by default is +/assets+.

0 notes on commit e746c40

Please sign in to comment.
Something went wrong with that request. Please try again.