From ed1dfaf48da81fa5d88248950419b3a552b44ecf Mon Sep 17 00:00:00 2001 From: Richard Hulse Date: Thu, 1 Sep 2011 13:28:33 +1200 Subject: update pipeline docs to reflect new defaults Production section has been changed to reflect the new default of precompilation and using the asset manifest. Development has been swapped around to reflect the new default (debug mode is on). Other changes to support this elsewhere. --- railties/guides/source/asset_pipeline.textile | 125 +++++++++++++++++++------- 1 file changed, 93 insertions(+), 32 deletions(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index d621dd5a70..f62b7e5c65 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -222,59 +222,76 @@ Keep in mind that the order of these pre-processors is important. For example, i h3. In Development -In the development environment assets are compiled and cached on the first request after the server is started. Sprockets sets a +must-validate+ Cache-Control HTTP header to reduce request overhead on subsequent requests - on these the browser gets a 304 (not-modified) response. +In development mode assets are served as separate files in the order they are specified in the manifest file. -If any of the files in the manifest have changed between requests, the server responds with a new compiled file. - -h4. Debugging Assets - -You can put +?debug_assets=true+ or +?debug_assets=1+ at the end of a URL or set +config.assets.debug+ and Sprockets expands the lines which load the assets. For example, if you had an +app/assets/javascripts/application.js+ file containing these lines: +This manifest +application.js+: -//= require "projects" -//= require "tickets" +//= require core +//= require projects +//= require tickets -By default, this only renders this line when used with +<%= javascript_include_tag "application" %>+ in a view or layout: +would generate this HTML: - + + + -When the +debug_assets+ parameter is set, this line is expanded out into three separate lines, separating out the combined file into their parts. +h4. Turning Debugging off + +You can turn off debug mode by updating +development.rb+ to include: + + +config.assets.debug = false + + +When debug mode is off Sprockets will concatenate and run the necessary preprocessors on all files, generating the following HTML: - - -This allows the individual parts of an asset to be rendered and debugged separately. +Assets are compiled and cached on the first request after the server is started. Sprockets sets a +must-validate+ Cache-Control HTTP header to reduce request overhead on subsequent requests - on these the browser gets a 304 (not-modified) response. + +If any of the files in the manifest have changed between requests, the server responds with a new compiled file. + +You can put +?debug_assets=true+ or +?debug_assets=1+ at the end of a URL to enable debug mode on-demand, and this will render indivudual tags for each file. This is useful for tracking down exact line numbers when debugging. + +You could potentially also enable compression in development mode as a sanity check, and disable it on-demand as required for debugging. -NOTE. Assets debugging is turned on by default in development and test environments. h3. In Production -In the production environment, assets are served slightly differently. +In the production environment Rails uses the fingerprinting scheme outlined above. By default it is assumed that assets have been precompiled and will be served as static assets by your web server. -On the first request the assets are compiled and cached as described above, however the manifest names are altered to include an MD5 hash. Files names typically look like these: +During the precompilation phase an MD5 is generated from the contents of the compiled files, and inserted into the filenames as they are written to disc. These fingerprinted names are used by the Rails helpers in place of the manifest name. - -/assets/application-908e25f4bf641868d8683022a5b62f54.js -/assets/application-4dd5b109ee3439da54f5bdfd78a80473.css - +For example this: -The MD5 is generated from the contents of the compiled files, and is included in the HTTP +Content-MD5+ header. + +<%= javascript_include_tag "application" %> +<%= stylesheet_link_tag "application" %> + -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. +generates something like this: + + + + + -This behavior is controlled by the setting of +config.assets.digest+ setting in Rails (which is +true+ for production, +false+ for everything else). +The fingerprinting behavior is controlled by the setting of +config.assets.digest+ setting in Rails (which is +true+ for production, +false+ for everything else). under normal circumstances the default options should not be changed. h4. Precompiling Assets -Even though assets are served by Rack::Cache with far-future headers, in high traffic sites this may not be fast enough. +Rails comes bundled with a rake task to compile the asset manifests and other files in the pipeline to disc. -Rails comes bundled with a rake task to compile the manifests to files on disc. These are located in the +public/assets+ directory where they are served by your web server instead of the Rails application. +Compiled assets are written to the location specified in +config.assets.prefix+. The default setting will use the +public/assets+ directory. + +You must use this task either during deployment or locally if you do not have write access to your production filesystem. The rake task is: @@ -288,7 +305,7 @@ Capistrano (v2.8.0+) has a recipe to handle this in deployment. Add the followin load 'deploy/assets' -This links the folder specified in +config.assets.prefix+ to +shared/assets+. If you already use this folder you'll need to write your own deployment task. +This links the folder specified in +config.assets.prefix+ to +shared/assets+. If you already use this shared folder you'll need to write your own deployment task. It is important that this folder is shared between deployments so that remotely cached pages that reference the old compiled assets still work for the life of the cached page. @@ -298,13 +315,13 @@ The default matcher for compiling files includes +application.js+, +application. [ /\w+\.(?!js|css).+/, /application.(css|js)$/ ] -If you have other manifests or individual stylesheets and JavaScript files to include, you can append them to the +precompile+ array: +If you have other manifests or individual stylesheets and JavaScript files to include, you can add them to the +precompile+ array: config.assets.precompile += ['admin.js', 'admin.css', 'swfObject.js'] -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: +The rake task also generates a +manifest.yml+ that contains a list with all your assets and their respective fingerprints. This is used by the Rails helper methods and avoids handing the mapping requests back to Sprockets. Manifest file typically look like this: --- @@ -315,8 +332,17 @@ application.js: application-3fdab497b8fb70d20cfc5495239dfc29.js application.css: application-8af74128f904600e41a6e39241464e03.css -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. +The default location for the manifest is the root of the location specified in +config.assets.prefix+ ('/assets' by default). + +This can be changed with the +config.assets.manifest+ option. A fully specified path is required: + +config.assets.manifest = '/path/to/some/other/location' + + +NOTE: If there are missing precompiled files in production you will get an "AssetNoPrecompiledError" exception indicating the name of the missing file. + +h5. Server Configuration 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. @@ -370,10 +396,23 @@ location ~ ^/(assets)/ { } -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. +h4. Live Compilation -h3. Customizing the Pipeline +In some circumstances you may wish to use live compilation. In this mode all requests for assets in the Pipeline are handled by Sprockets directly. + +To enable this options set: + + +config.assets.compile = true + + +On the first request the assets are compiled and cached as outlined in development above, and the manifest names used in the helpers are altered to include the MD5 hash. + +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. + +This mode uses more memory and is lower performance than the default. It is not recommended. +h3. Customizing the Pipeline h4. CSS Compression @@ -475,6 +514,10 @@ config.assets.enabled = true # Version of your assets, change this if you want to expire all your assets config.assets.version = '1.0' + +# Change the path that assets are served from +# config.assets.prefix = "/assets" + In +development.rb+: @@ -493,6 +536,11 @@ And in +production.rb+: # Compress JavaScripts and CSS config.assets.compress = true +# Choose the compressors to use +# config.assets.js_compressor = :uglifier +# config.assets.css_compressor = :yui + + # Don't fallback to assets pipeline if a precompiled asset is missed config.assets.compile = false @@ -507,3 +555,16 @@ config.assets.digest = true There are no changes to +test.rb+. + +The following should also be added to +Gemfile+: + + +# Gems used only for assets and not required +# in production environments by default. +group :assets do + gem 'sass-rails', " ~> 3.1.0" + gem 'coffee-rails', "~> 3.1.0" + gem 'uglifier' +end + + -- cgit v1.2.3 From 4ba35dd26b8f02ab851e9d8431a1fe78264e2d51 Mon Sep 17 00:00:00 2001 From: Guillermo Iguaran Date: Thu, 1 Sep 2011 00:35:01 -0500 Subject: Giving info about what are the defaults for test environment --- railties/guides/source/asset_pipeline.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index f62b7e5c65..8bcddfbb4b 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -554,7 +554,7 @@ config.assets.digest = true # config.assets.precompile += %w( search.js ) -There are no changes to +test.rb+. +There are no changes to +test.rb+. For test environment by default +config.assets.compile+ is true and +config.assets.compress+, +config.assets.debug+ and +config.assets.digest+ are false The following should also be added to +Gemfile+: -- cgit v1.2.3 From 418e321b506645bc0fb69116f01de41546a8cacf Mon Sep 17 00:00:00 2001 From: Guillermo Iguaran Date: Thu, 1 Sep 2011 01:01:31 -0500 Subject: Fixing sass-rails helpers methods examples --- railties/guides/source/asset_pipeline.textile | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index 8bcddfbb4b..9ff4f0d062 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -158,13 +158,13 @@ h5. CSS and SCSS When using the asset pipeline, paths to assets must be re-written and +sass-rails+ provides +_url+ and +_path+ helpers for the following asset classes: image, font, video, audio, javascript, stylesheet. -* +image_url("rails.png")+ becomes +url(/assets/rails.png)+ -* +image_path("rails.png")+ becomes +"/assets/rails.png"+. +* +image-url("rails.png")+ becomes +url(/assets/rails.png)+ +* +image-path("rails.png")+ becomes +"/assets/rails.png"+. The more generic form can also be used but the asset path and class must both be specified: -* +asset_url("rails.png", "image")+ becomes +url(/assets/rails.png)+ -* +asset_path("rails.png", "image")+ becomes +"/assets/rails.png"+ +* +asset-url("rails.png", image)+ becomes +url(/assets/rails.png)+ +* +asset-path("rails.png", image)+ becomes +"/assets/rails.png"+ h4. Manifest Files and Directives -- cgit v1.2.3 From fdf2f519bd948003b851a1eff8a6f157297a46ad Mon Sep 17 00:00:00 2001 From: Guillermo Iguaran Date: Thu, 1 Sep 2011 01:15:19 -0500 Subject: Add reference to ExecJS in JavaScript Compression section --- railties/guides/source/asset_pipeline.textile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index 9ff4f0d062..b06abc82cf 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -426,7 +426,7 @@ config.assets.css_compressor = :yui The +config.assets.compress+ must be set to +true+ to enable CSS compression -h4. JavaScript +h4. JavaScript Compression Possible options for JavaScript compression are +:closure+, +:uglifier+ and +:yui+. These require the use of the +closure-compiler+, +uglifier+ or +yui-compressor+ gems respectively. @@ -440,6 +440,8 @@ config.assets.js_compressor = :uglifier The +config.assets.compress+ must be set to +true+ to enable JavaScript compression +NOTE: You will need a "ExecJS":https://github.com/sstephenson/execjs#readme - supported runtime in order to use +uglifier+. If you are using Mac OS X or Windows you have a JavaScript engine in your operating system. Check "ExecJS":https://github.com/sstephenson/execjs#readme documentation to know all supported JavaScript runtimes. + h4. Using Your Own Compressor The compressor config settings for CSS and JavaScript also take any Object. This object must have a +compress+ method that takes a string as the sole argument and it must return a string. -- cgit v1.2.3 From 72fea6d2ebd9a40d78f0d6ad0fdbdf80298458e9 Mon Sep 17 00:00:00 2001 From: Guillermo Iguaran Date: Thu, 1 Sep 2011 01:18:20 -0500 Subject: Adding reference about ExecJS for CoffeeScript --- railties/guides/source/asset_pipeline.textile | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index b06abc82cf..e428684079 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -89,10 +89,12 @@ In previous versions of Rails, all assets were located in subdirectories of +pub This is not to say that assets can (or should) no longer be placed in +public+; they still can be and will be served as static files by the application or web server. You would only use +app/assets+ if you wish your files to undergo some pre-processing before they are served. -When a scaffold or controller is generated for the application, Rails also generates a JavaScript file (or CoffeeScript file if the +coffee-script+ gem is in the +Gemfile+) and a Cascading Style Sheet file (or SCSS file if +sass-rails+ is in the +Gemfile+) for that controller. +When a scaffold or controller is generated for the application, 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. For example, if a +ProjectsController+ is generated, there will be a new file at +app/assets/javascripts/projects.js.coffee+ and another at +app/assets/stylesheets/projects.css.scss+. You should put any JavaScript or CSS unique to a controller inside their respective asset files, as these files can then be loaded just for these controllers with lines such as +<%= javascript_include_tag params[:controller] %>+ or +<%= stylesheet_link_tag params[:controller] %>+. +NOTE: You will need a "ExecJS":https://github.com/sstephenson/execjs#readme - supported runtime in order to use CoffeeScript. If you are using Mac OS X or Windows you have a JavaScript runtime installed in your operating system. Check "ExecJS":https://github.com/sstephenson/execjs#readme documentation to know all supported JavaScript runtimes. + h4. Asset Organization Assets can be placed inside an application in one of three locations: +app/assets+, +lib/assets+ or +vendor/assets+. @@ -440,7 +442,7 @@ config.assets.js_compressor = :uglifier The +config.assets.compress+ must be set to +true+ to enable JavaScript compression -NOTE: You will need a "ExecJS":https://github.com/sstephenson/execjs#readme - supported runtime in order to use +uglifier+. If you are using Mac OS X or Windows you have a JavaScript engine in your operating system. Check "ExecJS":https://github.com/sstephenson/execjs#readme documentation to know all supported JavaScript runtimes. +NOTE: You will need a "ExecJS":https://github.com/sstephenson/execjs#readme - supported runtime in order to use +uglifier+. If you are using Mac OS X or Windows you have installed a JavaScript runtime in your operating system. Check "ExecJS":https://github.com/sstephenson/execjs#readme documentation to know all supported JavaScript runtimes. h4. Using Your Own Compressor -- cgit v1.2.3 From 5421d4d0161949e24f63bab30b82be694761a6d4 Mon Sep 17 00:00:00 2001 From: Richard Hulse Date: Thu, 1 Sep 2011 18:25:24 +1200 Subject: pipeline docs - spelling and some whitespace --- railties/guides/source/asset_pipeline.textile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index e428684079..a0e51aa57c 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -282,7 +282,7 @@ generates something like this: - + The fingerprinting behavior is controlled by the setting of +config.assets.digest+ setting in Rails (which is +true+ for production, +false+ for everything else). under normal circumstances the default options should not be changed. @@ -375,7 +375,7 @@ For Apache: # 2 lines to serve pre-gzipped version RewriteCond %{REQUEST_FILENAME}.gz -s RewriteRule ^(.+) $1.gz [L] - + # without it, Content-Type will be "application/x-gzip" ForceType text/css @@ -402,7 +402,7 @@ h4. Live Compilation In some circumstances you may wish to use live compilation. In this mode all requests for assets in the Pipeline are handled by Sprockets directly. -To enable this options set: +To enable this option set: config.assets.compile = true @@ -442,7 +442,7 @@ config.assets.js_compressor = :uglifier The +config.assets.compress+ must be set to +true+ to enable JavaScript compression -NOTE: You will need a "ExecJS":https://github.com/sstephenson/execjs#readme - supported runtime in order to use +uglifier+. If you are using Mac OS X or Windows you have installed a JavaScript runtime in your operating system. Check "ExecJS":https://github.com/sstephenson/execjs#readme documentation to know all supported JavaScript runtimes. +NOTE: You will need a "ExecJS":https://github.com/sstephenson/execjs#readme - supported runtime in order to use +uglifier+. If you are using Mac OS X or Windows you have installed a JavaScript runtime in your operating system. Check "ExecJS":https://github.com/sstephenson/execjs#readme documentation to know all supported JavaScript runtimes. h4. Using Your Own Compressor @@ -506,7 +506,7 @@ TODO: Registering gems on "Tilt":https://github.com/rtomayko/tilt enabling Sproc h3. Upgrading from Old Versions of Rails -There are two issues when upgrading. The first is moving the files to the new locations. See the section above for guidance on the correct locations for different file types. +There are two issues when upgrading. The first is moving the files to the new locations. See the section above for guidance on the correct locations for different file types. The second is updating the various environment files with the correct default options. The following changes reflect the defaults in version 3.1.0. -- cgit v1.2.3 From 1f998c7578d343310a4309bc0b06af224132648d Mon Sep 17 00:00:00 2001 From: Richard Hulse Date: Thu, 1 Sep 2011 21:15:06 +1200 Subject: pipeline docs improvement Some cleaning up of whitespace/punctuation and text refinements to clarify some things. --- railties/guides/source/asset_pipeline.textile | 45 +++++++++++++++------------ 1 file changed, 25 insertions(+), 20 deletions(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index a0e51aa57c..3ed75a28ef 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -105,13 +105,17 @@ Assets can be placed inside an application in one of three locations: +app/asset +vendor/assets+ is for assets that are owned by outside entities, such as code for JavaScript plugins. -All subdirectories that exist within these three locations are added to the search path for Sprockets (visible by calling +Rails.application.config.assets.paths+ in a console). When an asset is requested, these paths are looked through to see if they contain an asset matching the name specified. Once an asset has been found, it's processed by Sprockets and served. +All subdirectories that exist within these three locations are added to the search path for Sprockets (visible by calling +Rails.application.config.assets.paths+ in a console). When an asset is requested, these paths are traversed to see if they contain an asset matching the name specified. Once an asset has been found, it's processed by Sprockets and served. -h4. Coding Links to Assets +You can add additional (fully qualified) paths to the pipeline in +application.rb+. For example: + + +config.assets.paths << File.join(Rails.root, 'app', 'assets', 'flash') + -To access assets, you use the same tags that you are generally familiar with: +h4. Coding Links to Assets -Sprockets does not add any new methods to require your assets, you still use the familiar +javascript_include_tag+ and +stylesheet_link_tag+. +Sprockets does not add any new methods to access your assets - you still use the familiar +javascript_include_tag+ and +stylesheet_link_tag+. <%= stylesheet_link_tag "application" %> @@ -124,17 +128,17 @@ In regular views you can access images in the +assets/images+ directory like thi <%= image_tag "rails.png" %> -Images can be organized into directories if required, and they can be accessed by specifying the directory's name in the tag: +Provided that the pipeline is enabled within your application (and not disabled in the current environment context), this file is served by Sprockets. If a file exists at +public/assets/rails.png+ it is served by the webserver. - -<%= image_tag "icons/rails.png" %> - +Alternatively, a request for a file with an MD5 hash such as +public/assets/rails-af27b6a414e6da00003503148be9b409.png+ is treated the same way. How these hashes are generated is covered in the "Production Assets":#production_assets section later on in this guide. -Providing that assets are enabled within your application (+config.assets.enabled+ in the current environment's file is not set to +false+), this file is served by Sprockets unless a file at +public/assets/rails.png+ exists, in which case that file is served. +Sprockets will also look through the paths specified in +config.assets.paths+ which includes the standard application paths and any path added by Rails engines. -Alternatively, a file with an MD5 hash after its name such as +public/assets/rails-af27b6a414e6da00003503148be9b409.png+ is also picked up by Sprockets. How these hashes are generated is covered in the "Production Assets":#production_assets section later on in this guide. +Images can also be organized into subdirectories if required, and they can be accessed by specifying the directory's name in the tag: -Otherwise, Sprockets looks through the available paths until it finds a file that matches the name and then serves it, first looking in the application's assets directories and then falling back to the various engines of the application. + +<%= image_tag "icons/rails.png" %> + If you want to use a "css data URI":http://en.wikipedia.org/wiki/Data_URI_scheme -- a method of embedding the image data directly into the CSS file -- you can use the +asset_data_uri+ helper. @@ -256,7 +260,7 @@ When debug mode is off Sprockets will concatenate and run the necessary preproce -Assets are compiled and cached on the first request after the server is started. Sprockets sets a +must-validate+ Cache-Control HTTP header to reduce request overhead on subsequent requests - on these the browser gets a 304 (not-modified) response. +Assets are compiled and cached on the first request after the server is started. Sprockets sets a +must-validate+ Cache-Control HTTP header to reduce request overhead on subsequent requests -- on these the browser gets a 304 (not-modified) response. If any of the files in the manifest have changed between requests, the server responds with a new compiled file. @@ -285,7 +289,9 @@ generates something like this: -The fingerprinting behavior is controlled by the setting of +config.assets.digest+ setting in Rails (which is +true+ for production, +false+ for everything else). under normal circumstances the default options should not be changed. +The fingerprinting behavior is controlled by the setting of +config.assets.digest+ setting in Rails (which is +true+ for production, +false+ for everything else). + +NOTE: Under normal circumstances the default options should not be changed. If there are no digests in the filenames, and far-future headers are set, remote clients will never know to refetch the files when their content changes. h4. Precompiling Assets @@ -366,7 +372,7 @@ For Apache: TODO: nginx instructions -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: +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: For Apache: @@ -418,7 +424,7 @@ h3. Customizing the Pipeline h4. CSS Compression -There is currently one option for compressing CSS - YUI. This Gem extends the CSS syntax and offers minification. +There is currently one option for compressing CSS, YUI. This Gem extends the CSS syntax and offers minification. The following line enables YUI compression, and requires the +yui-compressor+ gem. @@ -442,7 +448,7 @@ config.assets.js_compressor = :uglifier The +config.assets.compress+ must be set to +true+ to enable JavaScript compression -NOTE: You will need a "ExecJS":https://github.com/sstephenson/execjs#readme - supported runtime in order to use +uglifier+. If you are using Mac OS X or Windows you have installed a JavaScript runtime in your operating system. Check "ExecJS":https://github.com/sstephenson/execjs#readme documentation to know all supported JavaScript runtimes. +NOTE: You will need a "ExecJS":https://github.com/sstephenson/execjs#readme -- supported runtime in order to use +uglifier+. If you are using Mac OS X or Windows you have installed a JavaScript runtime in your operating system. Check "ExecJS":https://github.com/sstephenson/execjs#readme documentation to know all supported JavaScript runtimes. h4. Using Your Own Compressor @@ -490,7 +496,7 @@ WARNING: If you are upgrading an existing application and intend to use this opt h3. How Caching Works -Sprockets uses the default rails cache store to cache assets in dev and production. The only difference is file names are fingerprinted and get far-future headers in production. +Sprockets uses the default rails cache store to cache assets in development and production. TODO: Add more about changing the default store. @@ -544,11 +550,10 @@ config.assets.compress = true # config.assets.js_compressor = :uglifier # config.assets.css_compressor = :yui - # Don't fallback to assets pipeline if a precompiled asset is missed config.assets.compile = false -# Generate digests for assets URLs +# Generate digests for assets URLs. config.assets.digest = true # Defaults to Rails.root.join("public/assets") @@ -558,7 +563,7 @@ config.assets.digest = true # config.assets.precompile += %w( search.js ) -There are no changes to +test.rb+. For test environment by default +config.assets.compile+ is true and +config.assets.compress+, +config.assets.debug+ and +config.assets.digest+ are false +There are no changes to +test.rb+. The defaults in the test environment are: +config.assets.compile+ is true and +config.assets.compress+, +config.assets.debug+ and +config.assets.digest+ are false. The following should also be added to +Gemfile+: -- cgit v1.2.3 From cfd785f910fc914c576133fee263875833ba0c92 Mon Sep 17 00:00:00 2001 From: Richard Hulse Date: Thu, 1 Sep 2011 21:20:26 +1200 Subject: Move css data URI into css/erb section --- railties/guides/source/asset_pipeline.textile | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index 3ed75a28ef..cfed1b5bdf 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -140,14 +140,6 @@ Images can also be organized into subdirectories if required, and they can be ac <%= image_tag "icons/rails.png" %> -If you want to use a "css data URI":http://en.wikipedia.org/wiki/Data_URI_scheme -- a method of embedding the image data directly into the CSS file -- you can use the +asset_data_uri+ helper. - - -#logo { background: url(<%= asset_data_uri 'logo.png' %>) } - - -This inserts a correctly-formatted data URI into the CSS source. - h5. CSS and ERB If you add an +erb+ extension to a CSS asset, making it something such as +application.css.erb+, then you can use the +asset_path+ helper in your CSS rules: @@ -158,6 +150,14 @@ If you add an +erb+ extension to a CSS asset, making it something such as +appli This writes the path to the particular asset being referenced. In this example, it would make sense to have an image in one of the asset load paths, such as +app/assets/images/image.png+, which would be referenced here. If this image is already available in +public/assets+ as a fingerprinted file, then that path is referenced. +If you want to use a "css data URI":http://en.wikipedia.org/wiki/Data_URI_scheme -- a method of embedding the image data directly into the CSS file -- you can use the +asset_data_uri+ helper. + + +#logo { background: url(<%= asset_data_uri 'logo.png' %>) } + + +This inserts a correctly-formatted data URI into the CSS source. + Note that the closing tag cannot be of the style +-%>+. h5. CSS and SCSS -- cgit v1.2.3 From 3461a5d4368ab0e41f28d831170794f967286611 Mon Sep 17 00:00:00 2001 From: Roy Tomeij Date: Thu, 1 Sep 2011 17:24:26 +0200 Subject: Change "SCSS" to "Sass" in sentences where it's referred to as "language", because Sass is the language (SCSS is one possible syntax within the Sass language), as per documentation on sass-lang.com. --- railties/guides/source/asset_pipeline.textile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index cfed1b5bdf..550485d038 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -13,7 +13,7 @@ endprologue. h3. What is the Asset Pipeline? -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. +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, Sass and ERB. 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 through ActionPack which depends on the +sprockets+ gem, by default. @@ -36,7 +36,7 @@ The default behavior in Rails 3.1 and onward is to concatenate all files into on The second feature is to minify or compress assets. For CSS, this usually involves removing whitespace and comments. For JavaScript, more complex processes can be applied. You can choose from a set of built in options or specify your own. -The third feature is the ability to code these assets using another language, or language extension. These include SCSS or Sass for CSS, CoffeeScript for JavaScript, and ERB for both. +The third feature is the ability to code these assets using another language, or language extension. These include Sass for CSS, CoffeeScript for JavaScript, and ERB for both. h4. What is Fingerprinting and Why Should I Care? @@ -108,7 +108,7 @@ Assets can be placed inside an application in one of three locations: +app/asset All subdirectories that exist within these three locations are added to the search path for Sprockets (visible by calling +Rails.application.config.assets.paths+ in a console). When an asset is requested, these paths are traversed to see if they contain an asset matching the name specified. Once an asset has been found, it's processed by Sprockets and served. You can add additional (fully qualified) paths to the pipeline in +application.rb+. For example: - + config.assets.paths << File.join(Rails.root, 'app', 'assets', 'flash') @@ -160,7 +160,7 @@ This inserts a correctly-formatted data URI into the CSS source. Note that the closing tag cannot be of the style +-%>+. -h5. CSS and SCSS +h5. CSS and Sass When using the asset pipeline, paths to assets must be re-written and +sass-rails+ provides +_url+ and +_path+ helpers for the following asset classes: image, font, video, audio, javascript, stylesheet. @@ -289,7 +289,7 @@ generates something like this: -The fingerprinting behavior is controlled by the setting of +config.assets.digest+ setting in Rails (which is +true+ for production, +false+ for everything else). +The fingerprinting behavior is controlled by the setting of +config.assets.digest+ setting in Rails (which is +true+ for production, +false+ for everything else). NOTE: Under normal circumstances the default options should not be changed. If there are no digests in the filenames, and far-future headers are set, remote clients will never know to refetch the files when their content changes. -- cgit v1.2.3 From ca7c37a660b66b6b3cdd7fe4ab850ea5a32cc2c0 Mon Sep 17 00:00:00 2001 From: Richard Hulse Date: Fri, 2 Sep 2011 08:39:16 +1200 Subject: fix some minor omissions in pipeline docs --- railties/guides/source/asset_pipeline.textile | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index 550485d038..e40310a9ec 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -89,6 +89,8 @@ In previous versions of Rails, all assets were located in subdirectories of +pub This is not to say that assets can (or should) no longer be placed in +public+; they still can be and will be served as static files by the application or web server. You would only use +app/assets+ if you wish your files to undergo some pre-processing before they are served. +In production, the default is to precompile these files to +public/assets+ so that they can be more efficiently delivered by the webserver. + When a scaffold or controller is generated for the application, 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. For example, if a +ProjectsController+ is generated, there will be a new file at +app/assets/javascripts/projects.js.coffee+ and another at +app/assets/stylesheets/projects.css.scss+. You should put any JavaScript or CSS unique to a controller inside their respective asset files, as these files can then be loaded just for these controllers with lines such as +<%= javascript_include_tag params[:controller] %>+ or +<%= stylesheet_link_tag params[:controller] %>+. @@ -241,11 +243,13 @@ This manifest +application.js+: would generate this HTML: - - - + + + +The +body+ param is required by Sprockets. + h4. Turning Debugging off You can turn off debug mode by updating +development.rb+ to include: @@ -264,7 +268,16 @@ Assets are compiled and cached on the first request after the server is started. If any of the files in the manifest have changed between requests, the server responds with a new compiled file. -You can put +?debug_assets=true+ or +?debug_assets=1+ at the end of a URL to enable debug mode on-demand, and this will render indivudual tags for each file. This is useful for tracking down exact line numbers when debugging. +You can put +?debug_assets=true+ or +?debug_assets=1+ at the end of a URL to enable debug mode on-demand, and this will render individual tags for each file. This is useful for tracking down exact line numbers when debugging. + +Debug can also be set in the Rails helper methods: + + +<%= stylesheet_link_tag "application", :debug => true %> +<%= javascript_include_tag "application", :debug => true %> + + +Don't forget to remove this before deploying to production! You could potentially also enable compression in development mode as a sanity check, and disable it on-demand as required for debugging. @@ -291,7 +304,7 @@ generates something like this: The fingerprinting behavior is controlled by the setting of +config.assets.digest+ setting in Rails (which is +true+ for production, +false+ for everything else). -NOTE: Under normal circumstances the default options should not be changed. If there are no digests in the filenames, and far-future headers are set, remote clients will never know to refetch the files when their content changes. +NOTE: Under normal circumstances the default option should not be changed. If there are no digests in the filenames, and far-future headers are set, remote clients will never know to refetch the files when their content changes. h4. Precompiling Assets -- cgit v1.2.3 From d20281add192e5afba66e555ce67cf73943b033b Mon Sep 17 00:00:00 2001 From: Andrew Olson Date: Fri, 2 Sep 2011 11:48:45 -0400 Subject: Fixing guides validation errors. --- railties/guides/source/asset_pipeline.textile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index cfed1b5bdf..bbd2e24da5 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -62,11 +62,11 @@ This has several disadvantages:
  1. - Not all caches will cache content with a query string
    + Not all caches will cache content with a query string
    "Steve Souders recommends":http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/, "...avoiding a querystring for cacheable resources". He found that in these case 5-20% of requests will not be cached.
  2. - The file name can change between nodes in multi-server environments.
    + The file name can change between nodes in multi-server environments.
    The query string in Rails is based on the modification time of the files. When assets are deployed to a cluster, there is no guarantee that the timestamps will be the same, resulting in different values being used depending on which server handles the request.
@@ -91,7 +91,7 @@ This is not to say that assets can (or should) no longer be placed in +public+; When a scaffold or controller is generated for the application, 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. -For example, if a +ProjectsController+ is generated, there will be a new file at +app/assets/javascripts/projects.js.coffee+ and another at +app/assets/stylesheets/projects.css.scss+. You should put any JavaScript or CSS unique to a controller inside their respective asset files, as these files can then be loaded just for these controllers with lines such as +<%= javascript_include_tag params[:controller] %>+ or +<%= stylesheet_link_tag params[:controller] %>+. +For example, if a +ProjectsController+ is generated, there will be a new file at +app/assets/javascripts/projects.js.coffee+ and another at +app/assets/stylesheets/projects.css.scss+. You should put any JavaScript or CSS unique to a controller inside their respective asset files, as these files can then be loaded just for these controllers with lines such as +<%= javascript_include_tag params[:controller] %>+ or +<%= stylesheet_link_tag params[:controller] %>+. NOTE: You will need a "ExecJS":https://github.com/sstephenson/execjs#readme - supported runtime in order to use CoffeeScript. If you are using Mac OS X or Windows you have a JavaScript runtime installed in your operating system. Check "ExecJS":https://github.com/sstephenson/execjs#readme documentation to know all supported JavaScript runtimes. -- cgit v1.2.3 From 220c77dd68430cc150c61119a14c86dee659911c Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Fri, 2 Sep 2011 22:42:23 +0530 Subject: debug option to js, stylesheet tags are ignored when debug mode is off --- railties/guides/source/asset_pipeline.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index 73f77ac05e..86ae23ab11 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -277,7 +277,7 @@ Debug can also be set in the Rails helper methods: <%= javascript_include_tag "application", :debug => true %> -Don't forget to remove this before deploying to production! +The +:debug+ option is ignored if the debug mode is off. You could potentially also enable compression in development mode as a sanity check, and disable it on-demand as required for debugging. -- cgit v1.2.3 From 44284a613b3efe2319db3f84090c0004505942c1 Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Fri, 2 Sep 2011 22:57:03 +0530 Subject: Revert "Fixing guides validation errors." This reverts commit d20281add192e5afba66e555ce67cf73943b033b. Reason: This needs more investigation. Will apply when this is verified. --- railties/guides/source/asset_pipeline.textile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'railties/guides/source/asset_pipeline.textile') diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index 86ae23ab11..192c393dca 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -62,11 +62,11 @@ This has several disadvantages:
  1. - Not all caches will cache content with a query string
    + Not all caches will cache content with a query string
    "Steve Souders recommends":http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/, "...avoiding a querystring for cacheable resources". He found that in these case 5-20% of requests will not be cached.
  2. - The file name can change between nodes in multi-server environments.
    + The file name can change between nodes in multi-server environments.
    The query string in Rails is based on the modification time of the files. When assets are deployed to a cluster, there is no guarantee that the timestamps will be the same, resulting in different values being used depending on which server handles the request.
@@ -93,7 +93,7 @@ In production, the default is to precompile these files to +public/assets+ so th When a scaffold or controller is generated for the application, 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. -For example, if a +ProjectsController+ is generated, there will be a new file at +app/assets/javascripts/projects.js.coffee+ and another at +app/assets/stylesheets/projects.css.scss+. You should put any JavaScript or CSS unique to a controller inside their respective asset files, as these files can then be loaded just for these controllers with lines such as +<%= javascript_include_tag params[:controller] %>+ or +<%= stylesheet_link_tag params[:controller] %>+. +For example, if a +ProjectsController+ is generated, there will be a new file at +app/assets/javascripts/projects.js.coffee+ and another at +app/assets/stylesheets/projects.css.scss+. You should put any JavaScript or CSS unique to a controller inside their respective asset files, as these files can then be loaded just for these controllers with lines such as +<%= javascript_include_tag params[:controller] %>+ or +<%= stylesheet_link_tag params[:controller] %>+. NOTE: You will need a "ExecJS":https://github.com/sstephenson/execjs#readme - supported runtime in order to use CoffeeScript. If you are using Mac OS X or Windows you have a JavaScript runtime installed in your operating system. Check "ExecJS":https://github.com/sstephenson/execjs#readme documentation to know all supported JavaScript runtimes. -- cgit v1.2.3