From bc49d6d1eb075900657b0f94d03c51d18a95a54d Mon Sep 17 00:00:00 2001 From: Richard Hulse Date: Fri, 5 Aug 2011 20:46:20 +1200 Subject: [asset pipeline] fixed example Changed << to += because we are _concatenating_ this new array to the end of config array, NOT pushing this array in it. --- 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 51cb332e38..13e28a25ba 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -297,7 +297,7 @@ The default matcher for compiling files will include +application.js+, +applicat If you have other manifests or individual stylesheets and JavaScript files to include, you can append them to the +precompile+ array: -config.assets.precompile << ['admin.js', 'admin.css', 'swfObject.js'] +config.assets.precompile += ['admin.js', 'admin.css', 'swfObject.js'] 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. -- cgit v1.2.3 From b840d71bfb702b121b48832f984090e202793f10 Mon Sep 17 00:00:00 2001 From: Richard Hulse Date: Sun, 7 Aug 2011 09:37:39 +1200 Subject: [asset pipeline] Update Capistrano info v2.8.0 of Capistrano has a recipe to handle precompile and symlinking. --- railties/guides/source/asset_pipeline.textile | 10 ++++------ 1 file changed, 4 insertions(+), 6 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 13e28a25ba..3a87c90516 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -276,17 +276,15 @@ The rake task is: rake assets:precompile -You can run this as part of a Capistrano deployment: +Capistrano (v2.8.0+) has a recipe to to handle this in deployment. Add the following line to +Capfile+: -before 'deploy:symlink' do - run "cd #{release_path}; RAILS_ENV=#{rails_env} rake assets:precompile" -end +load 'deploy/assets' -If you are not precompiling your assets, and you are using the default cache file store (which is the file system), you will need to symlink +rails_root/tmp/cache/assets+ from the shared folder that is part of the Capistrano deployment structure in order to persist the cached file between deployments. +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. -TODO: Extend above task to allow for this and add task to set it up (See commits 8f0e0b6 and 704ee0df). Note: Capistrano folks are working on a recipe - update this when it available (see https://github.com/capistrano/capistrano/pull/35). +It is important for 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. The default matcher for compiling files will include +application.js+, +application.css+ and all files that do not end in +js+ or +css+: -- cgit v1.2.3 From 32da2f864eb9e1f626f25e5d46a38d0c0d214d15 Mon Sep 17 00:00:00 2001 From: Richard Hulse Date: Mon, 8 Aug 2011 18:02:19 +1200 Subject: [asset pipeline] update to reflect new sendfile header default X-Sendfile headers are now set to nil and are off by default. See commit eff7fddeb26eaa346827 --- railties/guides/source/asset_pipeline.textile | 6 ++---- 1 file changed, 2 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 3a87c90516..3eede31572 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -385,16 +385,14 @@ This is a handy option if you have any existing project (pre Rails 3.1) that alr h4. X-Sendfile Headers -The X-Sendfile header is a directive to the server to ignore the response from the application, and instead serve the file specified in the headers. In production Rails (via Sprockets) does not send the asset - just the location and a zero-length response - relying on the web server to do the file serving, which is usually faster. Both Apache and nginx support this option. +The X-Sendfile header is a directive to the server to ignore the response from the application, and instead serve the file specified in the headers. This option is off be default, but can be enabled if your server supports it. When enabled, this passes responsibility for serving the file to the web server, which is faster. -The configuration is available in config/environments/production.rb. +Apache and nginx support this option which is enabled in config/environments/production.rb. config.action_dispatch.x_sendfile_header = "X-Sendfile" # Use 'X-Accel-Redirect' for nginx -You should check that your server or hosting service actually supports this, otherwise comment it out. - WARNING: If you are upgrading an existing application and intend to use this option, take care to paste this configuration option only into +production.rb+ (and not +application.rb+) and any other environment you define with production behavior. h3. How Caching Works -- cgit v1.2.3 From 49e81f21a3e6facac06c49739644dbb36c94f794 Mon Sep 17 00:00:00 2001 From: Richard Hulse Date: Mon, 8 Aug 2011 22:21:25 +1200 Subject: [asset pipeline] update snippet to reflect patch Two commented lines in example to match the commit (8845ae683e2688) --- railties/guides/source/asset_pipeline.textile | 3 ++- 1 file changed, 2 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 3eede31572..8a4d61dc3a 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -390,7 +390,8 @@ The X-Sendfile header is a directive to the server to ignore the response from t Apache and nginx support this option which is enabled in config/environments/production.rb. -config.action_dispatch.x_sendfile_header = "X-Sendfile" # Use 'X-Accel-Redirect' for nginx +# config.action_dispatch.x_sendfile_header = "X-Sendfile" # for apache +# config.action_dispatch.x_sendfile_header = 'X-Accel-Redirect' # for nginx WARNING: If you are upgrading an existing application and intend to use this option, take care to paste this configuration option only into +production.rb+ (and not +application.rb+) and any other environment you define with production behavior. -- cgit v1.2.3 From c0c5d5fd2e40f89fa56bf1c6785a392077f4263a Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Mon, 15 Aug 2011 21:46:21 +0530 Subject: assets guide - add info about require_directory, minor rephrasings --- railties/guides/source/asset_pipeline.textile | 12 +++++++----- 1 file changed, 7 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 8a4d61dc3a..a83226aa21 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -166,7 +166,7 @@ The more generic form can also be used but the asset path and class must both be h4. Manifest Files and Directives -Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ - instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets will load the files specified, process them if necessary, concatenate them into one single file and then compress them (if +Rails.application.config.assets.compress+ is set to +true+). By serving one file rather than many, a page's load time is greatly reduced as there is not as many requests to make for each file. +Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ - instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets will load the files specified, process them if necessary, concatenate them into one single file and then compress them (if +Rails.application.config.assets.compress+ is set to +true+). By serving one file rather than many, the load time of pages are greatly reduced as there are not as many requests to make. For example, in the default Rails application there's a +app/assets/javascripts/application.js+ file which contains the following lines: @@ -176,9 +176,11 @@ For example, in the default Rails application there's a +app/assets/javascripts/ //= require_tree . -In JavaScript files, directives begin with +//=+. In this case, the following file is using the +require+ directive and the +require_tree+ directive. The +require+ directive tells Sprockets that we would like to require a file called +jquery.js+ that is available somewhere in the search path for Sprockets. By default, this is located inside the +vendor/assets/javascripts+ directory contained within the +jquery-rails+ gem. An identical event takes place for the +jquery_ujs+ require +In JavaScript files, the directives begin with +//=+. In this case, the file is using the +require+ and the +require_tree+ directives. The +require+ directive is used to tell Sprockets what are the files that we would like to require. Here, we are requiring the files +jquery.js+ and +jquery_ujs.js+ that are available somewhere in the search path for Sprockets. We need not supply the extensions explicitly. Sprockets will assume we are requiring a +.js+ file when done from within a +.js+ file. -The +require_tree .+ directive tells Sprockets to include _all_ JavaScript files in this directory into the output. Only a path relative to the file can be specified. +NOTE. In Rails 3.1, the +jquery.js+ and +jquery_ujs.js+ files are located inside the +vendor/assets/javascripts+ directory contained within the +jquery-rails+ gem. + +The +require_tree .+ directive tells Sprockets to include _all_ JavaScript files in this directory into the output. Only a path relative to the file can be specified. There is also a +require_directory+ directive which includes all JavaScript files only in the directory specified (no nesting). There's also a default +app/assets/stylesheets/application.css+ file which contains these lines: @@ -344,10 +346,10 @@ Possible options for JavaScript compression are +:closure+, +:uglifier+ and +:yu The default Gemfile includes "uglifier":https://github.com/lautis/uglifier. This gem wraps "UglifierJS":https://github.com/mishoo/UglifyJS (written for NodeJS) in Ruby. It compress your code by removing white spaces and other magical things like changing your +if+ and +else+ statements to ternary operators where possible. -The following line will invoke uglifier for JavaScript compression. +The following line will invoke +uglifier+ for JavaScript compression. -config.assets.js_compressor = :uglifier +config.assets.js_compressor = :uglifier The +config.assets.compress+ must be set to +true+ to enable JavaScript compression -- cgit v1.2.3 From f7626ea38ebf1a6efdd8b059204aa2d22e096f39 Mon Sep 17 00:00:00 2001 From: JESii Date: Mon, 15 Aug 2011 15:17:13 -0700 Subject: Updates to Asset Pipeline Guide Grammar/syntax/style changes: 1. Changed all 'we' to 'you' 2. Corrected typos 3. Make consistent styline (e.g., dashes & double-dash usage) 4. Change use of future tense (will...) to present tense (easier to read). --- railties/guides/source/asset_pipeline.textile | 90 +++++++++++++-------------- 1 file changed, 45 insertions(+), 45 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 a83226aa21..74a9e497f2 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -1,6 +1,6 @@ h2. Asset Pipeline -This guide will cover the ideology of the asset pipeline introduced in Rails 3.1. +This guide covers the ideology of the asset pipeline introduced in Rails 3.1. By referring to this guide you will be able to: * Understand what the asset pipeline is and what it does @@ -19,7 +19,7 @@ Prior to Rails 3.1 these features were added through third-party Ruby libraries 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. -In new Rails 3.1 application the asset pipeline is enable by default. It can be disabled in +application.rb+ by putting this line inside the +Application+ class definition: +In new Rails 3.1 application the asset pipeline is enabled by default. It can be disabled in +application.rb+ by putting this line inside the +Application+ class definition: config.assets.enabled = false @@ -30,17 +30,17 @@ It is recommended that you use the defaults for all new apps. h4. Main Features -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 needs to make to render a web page. While Rails already has a feature to concatenate these types of asset--by placing +:cache => true+ at the end of tags such as +javascript_include_tag+ and +stylesheet_link_tag+--, many people do not use it. +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 assetsi -- by placing +:cache => true+ at the end of tags such as +javascript_include_tag+ and +stylesheet_link_tag+ -- many people do not use it. -The default behavior in Rails 3.1 and onward is to concatenate all files into one master file each for JS and CSS. However, you can separate files or groups of files if required (see below). In production an MD5 fingerprint is inserted into each filename so that the file is cached by the web browser but can be invalidated if the fingerprint is altered. +The default behavior in Rails 3.1 and onward is to concatenate all files into one master file each for JS and CSS. However, you can separate files or groups of files if required (see below). In production, an MD5 fingerprint is inserted into each filename so that the file is cached by the web browser but can be invalidated if the fingerprint is altered. -The second feature is to minify or compress. 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 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. h4. What is Fingerprinting and Why Should I Care? -Fingerprinting is a technique where the filenames of content that is static or infrequently updated is altered to be unique to the content contained in the file. +Fingerprinting is a technique whereby the filenames of content that is static or infrequently updated is altered to be unique to the content contained in the file. When a filename is unique and based on its content, HTTP headers can be set to encourage caches everywhere (at ISPs, in browsers) to keep their own copy of the content. When the content is updated, the fingerprint will change and the remote clients will request the new file. This is generally known as _cachebusting_. @@ -52,7 +52,7 @@ global.css => global-908e25f4bf641868d8683022a5b62f54.css This is the strategy adopted by the Rails asset pipeline. -Rails old strategy was to append a query string to every asset linked with a built-in helper. In the source the generated code looked like this: +Rails' old strategy was to append a query string to every asset linked with a built-in helper. In the source the generated code looked like this: /stylesheets/global.css?1309495796 @@ -73,7 +73,7 @@ This has several disadvantages: The other problem is that when static assets are deployed with each new release of code, the mtime of *all* these files changes, forcing all remote clients to fetch them again, even when the content of those assets has not changed. -Fingerprinting avoids all these problems by ensuring filenames are consistent based on the content. +Fingerprinting avoids all these problems by ensuring filenames are consistent based on their content. More reading: @@ -83,11 +83,11 @@ More reading: h3. How to Use the Asset Pipeline -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 will be served by the Sprockets middleware included in the sprockets gem. +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. 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 will also generate a JavaScript file (or CoffeeScript if the +coffee-script+ gem is in the +Gemfile+) and a Cascading Style Sheet file (or SCSS if +sass-rails+ is in the +Gemfile+) file 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-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. 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] %>+. @@ -101,13 +101,13 @@ 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 will be 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 will be 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 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. h4. Coding Links to Assets -To access assets, we can use the same tags that we are generally familiar with: +To access assets, you use the same tags that you are generally familiar with: -Sprockets does not add any new methods to require your assets, we still use the familiar +javascript_include_tag+ and +stylesheet_link_tag+. +Sprockets does not add any new methods to require your assets, you still use the familiar +javascript_include_tag+ and +stylesheet_link_tag+. <%= stylesheet_link_tag "application" %> @@ -126,29 +126,29 @@ Images can be organized into directories if required, and they can be accessed b <%= image_tag "icons/rails.png" %> -Providing that assets are enabled within our application (+config.assets.enabled+ in the current environment's file is not set to +false+), this file will be served by Sprockets unless a file at +public/assets/rails.png+ exists, in which case that file will be served. +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. -Alternatively, a file with an MD5 hash after its name such as +public/assets/rails-af27b6a414e6da00003503148be9b409.png+ will also be picked up by Sprockets. How these hashes are generated is covered in the "Production Assets":#production_assets section later on in this guide. +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. -Otherwise, Sprockets will look through the available paths until it finds a file that matches the name and then will serve it, first looking in the application's assets directories and then falling back to the various engines of the application. +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. -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. +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 will insert a correctly formatted data URI into the CSS source. +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: +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: .class{background-image:<%= asset_path 'image.png' %>} -This will write 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 will be referenced. +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. Note that the closing tag cannot be of the style +-%>+. @@ -166,7 +166,7 @@ The more generic form can also be used but the asset path and class must both be h4. Manifest Files and Directives -Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ - instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets will load the files specified, process them if necessary, concatenate them into one single file and then compress them (if +Rails.application.config.assets.compress+ is set to +true+). By serving one file rather than many, the load time of pages are greatly reduced as there are not as many requests to make. +Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ -- instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets loads the files specified, processes them if necessary, concatenates them into one single file and then compresses them (if +Rails.application.config.assets.compress+ is set to +true+). By serving one file rather than many, the load time of pages are greatly reduced as there are fewer requests to make. For example, in the default Rails application there's a +app/assets/javascripts/application.js+ file which contains the following lines: @@ -176,7 +176,7 @@ For example, in the default Rails application there's a +app/assets/javascripts/ //= require_tree . -In JavaScript files, the directives begin with +//=+. In this case, the file is using the +require+ and the +require_tree+ directives. The +require+ directive is used to tell Sprockets what are the files that we would like to require. Here, we are requiring the files +jquery.js+ and +jquery_ujs.js+ that are available somewhere in the search path for Sprockets. We need not supply the extensions explicitly. Sprockets will assume we are requiring a +.js+ file when done from within a +.js+ file. +In JavaScript files, the directives begin with +//=+. In this case, the file is using the +require+ and the +require_tree+ directives. The +require+ directive is used to tell Sprockets the files that you wish to require. Here, you are requiring the files +jquery.js+ and +jquery_ujs.js+ that are available somewhere in the search path for Sprockets. You need not supply the extensions explicitly. Sprockets assumes you are requiring a +.js+ file when done from within a +.js+ file. NOTE. In Rails 3.1, the +jquery.js+ and +jquery_ujs.js+ files are located inside the +vendor/assets/javascripts+ directory contained within the +jquery-rails+ gem. @@ -191,13 +191,13 @@ There's also a default +app/assets/stylesheets/application.css+ file which conta */ -The directives that work in the JavaScript files will also work in stylesheets, obviously including stylesheets rather than JavaScript files. The +require_tree+ directive here works the same way as the JavaScript one, requiring all stylesheets from the current directory. +The directives that work in the JavaScript files also work in stylesheets, obviously including stylesheets rather than JavaScript files. The +require_tree+ directive here works the same way as the JavaScript one, requiring all stylesheets from the current directory. -In this example +require_self+ is used. This will put the CSS contained within the file (if any) at the top of any other CSS in this file unless +require_self+ is specified after another +require+ directive. +In this example +require_self+ is used. This puts the CSS contained within the file (if any) at the top of any other CSS in this file unless +require_self+ is specified after another +require+ directive. You can have as many manifest files as you need. For example the +admin.css+ and +admin.js+ manifest could contain the JS and CSS files that are used for the admin section of an application. -For some assets (like CSS) the compiled order is important. You can specify individual files and they will be compiled in the order specified: +For some assets (like CSS) the compiled order is important. You can specify individual files and they are compiled in the order specified: /* ... @@ -210,36 +210,36 @@ For some assets (like CSS) the compiled order is important. You can specify indi h4. Preprocessing -The file extensions used on an asset will determine what preprocessing will be applied. When a controller or a scaffold is generated with the default Rails gemset, a CoffeeScript file and a SCSS file will be 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 a +app/assets/stylesheets/projects.css.scss+ file. +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 a +app/assets/stylesheets/projects.css.scss+ file. -When these files are requested, they will be processed by the processors provided by the +coffee-script+ and +sass-rails+ gems and then sent back to the browser as JavaScript and CSS respectively. +When these files are requested, they are processed by the processors provided by the +coffee-script+ and +sass-rails+ gems and then sent back to the browser as JavaScript and CSS respectively. -Additional layers of pre-processing can be requested by adding other extensions, where each extension will be 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+ would first be processed as ERB, then SCSS and finally served as CSS. The same applies to a JavaScript file - +app/assets/javascripts/projects.js.coffee.erb+ would be process as ERB, CoffeeScript and served as JavaScript. +Additional layers of pre-processing 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, 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, CoffeeScript and served as JavaScript. -Keep in mind that the order of these pre-processors is important. For example, if we called our JavaScript file +app/assets/javascripts/projects.js.erb.coffee+ then it would be processed with the CoffeeScript interpreter first, which wouldn't understand ERB and therefore we would run into problems. +Keep in mind that the order of these pre-processors is important. For example, if you called your JavaScript file +app/assets/javascripts/projects.js.erb.coffee+ then it is processed with the CoffeeScript interpreter first, which wouldn't understand ERB and therefore you would run into problems. 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. -If any of the files in the manifest have changed between requests, the server will respond with a new compiled 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 and Sprockets will expand the lines which load the assets. For example, if we had an +app/assets/javascripts/application.js+ file containing these lines: +You can put +?debug_assets=true+ or +?debug_assets=1+ at the end of a URL and Sprockets expands the lines which load the assets. For example, if you had an +app/assets/javascripts/application.js+ file containing these lines: //= require "projects" //= require "tickets" -By default, this would only render this line when used with +<%= javascript_include_tag "application" %>+ in a view or layout: +By default, this only renders this line when used with +<%= javascript_include_tag "application" %>+ in a view or layout: -When the +debug_assets+ parameter is set, this line will be expanded out into three separate lines, separating out the combined file into their parts. +When the +debug_assets+ parameter is set, this line is expanded out into three separate lines, separating out the combined file into their parts. @@ -253,7 +253,7 @@ h3. In Production In the production environment, assets are served slightly differently. -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 will look like these: +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: /assets/application-908e25f4bf641868d8683022a5b62f54.js @@ -270,7 +270,7 @@ 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 manifests to files on disc. These are located in the +public/assets+ directory where they will be served by your web server instead of the Rails application. +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. The rake task is: @@ -278,7 +278,7 @@ The rake task is: rake assets:precompile -Capistrano (v2.8.0+) has a recipe to to handle this in deployment. Add the following line to +Capfile+: +Capistrano (v2.8.0+) has a recipe to handle this in deployment. Add the following line to +Capfile+: load 'deploy/assets' @@ -286,9 +286,9 @@ 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. -It is important for 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. +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. -The default matcher for compiling files will include +application.js+, +application.css+ and all files that do not end in +js+ or +css+: +The default matcher for compiling files includes +application.js+, +application.css+ and all files that do not end in +js+ or +css+: [ /\w+\.(?!js|css).+/, /application.(css|js)$/ ] @@ -320,7 +320,7 @@ For Apache: TODO: NGINX instructions -When files are precompiled Sprockets also creates "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: TODO: Apache instructions @@ -332,7 +332,7 @@ h4. CSS Compression There is currently one option for compressing CSS - YUI. This Gem extends the CSS syntax and offers minification. -The following line will enable YUI compression, and requires the +yui-compressor+ gem. +The following line enables YUI compression, and requires the +yui-compressor+ gem. config.assets.css_compressor = :yui @@ -344,9 +344,9 @@ h4. JavaScript Possible options for JavaScript compression are +:closure+, +:uglifier+ and +:yui+. These require the use of the +closure-compiler+, +uglifier+ or +yui-compressor+ gems respectively. -The default Gemfile includes "uglifier":https://github.com/lautis/uglifier. This gem wraps "UglifierJS":https://github.com/mishoo/UglifyJS (written for NodeJS) in Ruby. It compress your code by removing white spaces and other magical things like changing your +if+ and +else+ statements to ternary operators where possible. +The default Gemfile includes "uglifier":https://github.com/lautis/uglifier. This gem wraps "UglifierJS":https://github.com/mishoo/UglifyJS (written for NodeJS) in Ruby. It compresses your code by removing white space and other magical things like changing your +if+ and +else+ statements to ternary operators where possible. -The following line will invoke +uglifier+ for JavaScript compression. +The following line invokes +uglifier+ for JavaScript compression. config.assets.js_compressor = :uglifier @@ -356,7 +356,7 @@ The +config.assets.compress+ must be set to +true+ to enable JavaScript compress h4. Using Your Own Compressor -The compressor config settings for CSS and JavaScript will 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. +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. class Transformer @@ -366,7 +366,7 @@ class Transformer end -To enable this pass a +new+ Object to the config option in +application.rb+: +To enable this, pass a +new+ Object to the config option in +application.rb+: config.assets.css_compressor = Transformer.new @@ -387,7 +387,7 @@ This is a handy option if you have any existing project (pre Rails 3.1) that alr h4. X-Sendfile Headers -The X-Sendfile header is a directive to the server to ignore the response from the application, and instead serve the file specified in the headers. This option is off be default, but can be enabled if your server supports it. When enabled, this passes responsibility for serving the file to the web server, which is faster. +The X-Sendfile header is a directive to the server to ignore the response from the application, and instead serve the file specified in the headers. This option is off by default, but can be enabled if your server supports it. When enabled, this passes responsibility for serving the file to the web server, which is faster. Apache and nginx support this option which is enabled in config/environments/production.rb. -- cgit v1.2.3 From 6783ce0de4511e2568765f2e4919758d70690391 Mon Sep 17 00:00:00 2001 From: Jeff Dutil Date: Tue, 16 Aug 2011 23:35:40 -0400 Subject: Updates to remove extra whitespaces and notably fix a whitespace issue with ajax_on_rails causing a code block not to render the entire block properly. --- railties/guides/source/asset_pipeline.textile | 4 ---- 1 file changed, 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 74a9e497f2..8094ba18f2 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -27,7 +27,6 @@ config.assets.enabled = false It is recommended that you use the defaults for all new apps. - h4. Main Features 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 assetsi -- by placing +:cache => true+ at the end of tags such as +javascript_include_tag+ and +stylesheet_link_tag+ -- many people do not use it. @@ -80,7 +79,6 @@ More reading: * "Optimize caching":http://code.google.com/speed/page-speed/docs/caching.html * "Revving Filenames: don’t use querystring":http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/ - h3. How to Use the Asset Pipeline 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. @@ -324,7 +322,6 @@ When files are precompiled, Sprockets also creates a "Gzip":http://en.wikipedia. TODO: Apache instructions - h3. Customizing the Pipeline @@ -372,7 +369,6 @@ To enable this, pass a +new+ Object to the config option in +application.rb+: config.assets.css_compressor = Transformer.new - h4. Changing the _assets_ Path The public path that Sprockets uses by default is +/assets+. -- cgit v1.2.3 From 0b3b91cdcdfd54fc4a9e9bcb6be95ff487724e25 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Fri, 19 Aug 2011 19:45:55 -0300 Subject: Document debugging assets set by default for dev and test envs in the asset_pipeline guide. --- railties/guides/source/asset_pipeline.textile | 2 ++ 1 file changed, 2 insertions(+) (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 8094ba18f2..34ab00e80d 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -247,6 +247,8 @@ When the +debug_assets+ parameter is set, this line is expanded out into three s This allows the individual parts of an asset to be rendered and debugged separately. +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. -- cgit v1.2.3 From 18b2223b3290c4b3daa310edfc06b4d51161c312 Mon Sep 17 00:00:00 2001 From: "Andrey A.I. Sitnik" Date: Mon, 22 Aug 2011 09:36:36 +1100 Subject: Allow to debug assets by config.assets.debug --- 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 34ab00e80d..012149c40e 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -224,7 +224,7 @@ If any of the files in the manifest have changed between requests, the server re h4. Debugging Assets -You can put +?debug_assets=true+ or +?debug_assets=1+ at the end of a URL and Sprockets expands the lines which load the assets. For example, if you had an +app/assets/javascripts/application.js+ file containing these lines: +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: //= require "projects" -- cgit v1.2.3 From 3731a0f97ba37224984ec81aaf56b6b1013a85e1 Mon Sep 17 00:00:00 2001 From: Guillermo Iguaran Date: Wed, 24 Aug 2011 21:42:19 -0500 Subject: Update Debugging Assets section of Assets Pipeline guide --- railties/guides/source/asset_pipeline.textile | 9 ++++++++- 1 file changed, 8 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 012149c40e..4fbdda4c07 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -247,7 +247,14 @@ When the +debug_assets+ parameter is set, this line is expanded out into three s This allows the individual parts of an asset to be rendered and debugged separately. -NOTE. Assets debugging is turned on by default in development and test environments. +Additionally if the +config.assets.debug+ is set to true you can debug your assets passing the +:debug+ option to the assets tags: + + +<%= javascript_include_tag :application, :debug => true %> + + + +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. h3. In Production -- cgit v1.2.3 From 871696a01af853f10a33c4ff53f6d6ed795144b7 Mon Sep 17 00:00:00 2001 From: Igor Zubkov Date: Sun, 28 Aug 2011 23:08:06 +0300 Subject: Documentation fixes --- 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 4fbdda4c07..554246acb3 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -29,7 +29,7 @@ It is recommended that you use the defaults for all new apps. h4. Main Features -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 assetsi -- by placing +:cache => true+ at the end of tags such as +javascript_include_tag+ and +stylesheet_link_tag+ -- many people do not use it. +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. The default behavior in Rails 3.1 and onward is to concatenate all files into one master file each for JS and CSS. However, you can separate files or groups of files if required (see below). In production, an MD5 fingerprint is inserted into each filename so that the file is cached by the web browser but can be invalidated if the fingerprint is altered. @@ -133,7 +133,7 @@ Otherwise, Sprockets looks through the available paths until it finds a file tha 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' %>) +#logo { background: url(<%= asset_data_uri 'logo.png' %>) } This inserts a correctly-formatted data URI into the CSS source. @@ -143,7 +143,7 @@ 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: -.class{background-image:<%= asset_path 'image.png' %>} +.class { background-image: <%= asset_path 'image.png' %> } 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. @@ -282,7 +282,7 @@ Rails comes bundled with a rake task to compile the manifests to files on disc. The rake task is: -rake assets:precompile +bundle exec rake assets:precompile Capistrano (v2.8.0+) has a recipe to handle this in deployment. Add the following line to +Capfile+: -- cgit v1.2.3 From 2350fecd2251584d770afc4bd1764b3fe526ff70 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Tue, 30 Aug 2011 13:48:16 -0700 Subject: adds the asset pipeline guide to the index --- 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 554246acb3..2695ba9ec1 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -1,6 +1,6 @@ h2. Asset Pipeline -This guide covers the ideology of the asset pipeline introduced in Rails 3.1. +This guide covers the asset pipeline introduced in Rails 3.1. By referring to this guide you will be able to: * Understand what the asset pipeline is and what it does -- cgit v1.2.3 From e746c4047cd34accd7f63aa5d09cbb35011c24e2 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Wed, 31 Aug 2011 02:04:36 -0700 Subject: syncs assets guide with what's in 3-1-stable --- railties/guides/source/asset_pipeline.textile | 38 +++++++++++++++++++-------- 1 file changed, 27 insertions(+), 11 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 2695ba9ec1..96b11dbf63 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -15,7 +15,7 @@ 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. -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. +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. 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. @@ -27,6 +27,7 @@ config.assets.enabled = false It is recommended that you use the defaults for all new apps. + h4. Main Features 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 Fingerprinting avoids all these problems by ensuring filenames are consistent based on their content. +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. + More reading: * "Optimize caching":http://code.google.com/speed/page-speed/docs/caching.html * "Revving Filenames: don’t use querystring":http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/ + h3. How to Use the Asset Pipeline 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 This allows the individual parts of an asset to be rendered and debugged separately. -Additionally if the +config.assets.debug+ is set to true you can debug your assets passing the +:debug+ option to the assets tags: - - -<%= javascript_include_tag :application, :debug => true %> - - - -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. +NOTE. Assets debugging is turned on by default in development and test environments. h3. In Production @@ -271,7 +268,7 @@ The MD5 is generated from the contents of the compiled files, and is included in 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 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. +This behavior is controlled by the setting of +config.assets.digest+ setting in Rails (which is +true+ for production, +false+ for everything else). h4. Precompiling Assets @@ -307,6 +304,20 @@ If you have other manifests or individual stylesheets and JavaScript files to in 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: + + +--- +rails.png: rails-bd9ad5a560b5a3a7be0808c5cd76a798.png +jquery-ui.min.js: jquery-ui-7e33882a28fc84ad0e0e47e46cbf901c.min.js +jquery.min.js: jquery-8a50feed8d29566738ad005e19fe1c2d.min.js +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. + + 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. For Apache: @@ -325,12 +336,16 @@ For Apache: -TODO: NGINX instructions +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: TODO: Apache instructions +TODO: nginx instructions + +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. + h3. Customizing the Pipeline @@ -378,6 +393,7 @@ To enable this, pass a +new+ Object to the config option in +application.rb+: config.assets.css_compressor = Transformer.new + h4. Changing the _assets_ Path The public path that Sprockets uses by default is +/assets+. -- cgit v1.2.3 From 120b534d8e66a4b00764df3c08ff369c91756754 Mon Sep 17 00:00:00 2001 From: Andrew Olson Date: Wed, 31 Aug 2011 14:18:01 -0400 Subject: Fixing spelling, throught -> through. --- 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 96b11dbf63..76c8f520e5 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -15,7 +15,7 @@ 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. -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. +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. 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. -- cgit v1.2.3 From 054bdc1f59a035e1b50febac1487f9b982d6e63a Mon Sep 17 00:00:00 2001 From: Richard Hulse Date: Thu, 1 Sep 2011 09:11:00 +1200 Subject: Add section to pipeline docs to help people upgrading These are the options from a brand new app, and should help people get it right when upgrading. --- railties/guides/source/asset_pipeline.textile | 47 +++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) (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 76c8f520e5..222ee44de0 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -434,3 +434,50 @@ A good example of this is the +jquery-rails+ gem which comes with Rails as the s h3. Making Your Library or Gem a Pre-Processor TODO: Registering gems on "Tilt":https://github.com/rtomayko/tilt enabling Sprockets to find them. + +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. + +The second is updating the various environment files with the correct default options. The following changes reflect the defaults in version 3.1.0. + +In +application.rb+: + + +# Enable the asset pipeline +config.assets.enabled = true + +# Version of your assets, change this if you want to expire all your assets +config.assets.version = '1.0' + + +In +development.rb+: + + +# Do not compress assets +config.assets.compress = false + +# Expands the lines which load the assets +config.assets.debug = true + + +And in +production.rb+: + + +# Compress JavaScripts and CSS +config.assets.compress = true + +# Don't fallback to assets pipeline if a precompiled asset is missed +config.assets.compile = false + +# Generate digests for assets URLs +config.assets.digest = true + +# Defaults to Rails.root.join("public/assets") +# config.assets.manifest = YOUR_PATH + +# Precompile additional assets (application.js, application.css, and all non-JS/CSS are already added) +# config.assets.precompile += %w( search.js ) + + +There are no changes to +test.rb+. -- cgit v1.2.3 From 6ce6ba8638f4995e8e7d57b304fc31d6e27ae0e5 Mon Sep 17 00:00:00 2001 From: Kir Date: Thu, 1 Sep 2011 02:37:54 +0400 Subject: Instructions for nginx and apache added --- railties/guides/source/asset_pipeline.textile | 30 +++++++++++++++++++++++++-- 1 file changed, 28 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 222ee44de0..d621dd5a70 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -340,9 +340,35 @@ 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: -TODO: Apache instructions +For Apache: -TODO: nginx instructions + + + # 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 + + + + ForceType text/javascript + + + + +For nginx: + + +location ~ ^/(assets)/ { + root /path/to/public; + gzip_static on; # to serve pre-gzipped version + expires max; + add_header Cache-Control public; +} + 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. -- cgit v1.2.3 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 From a3edf3d2a307630980731b1963721c60ba2a14e0 Mon Sep 17 00:00:00 2001 From: Richard Hulse Date: Sat, 3 Sep 2011 09:11:20 +1200 Subject: fix YUI description YUI CSS compressor does not extend syntax! Also added link to more info --- 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 192c393dca..ef35d1ed76 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -437,7 +437,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. The "YUI CSS compressor":http://developer.yahoo.com/yui/compressor/css.html provides minification. The following line enables YUI compression, and requires the +yui-compressor+ gem. -- cgit v1.2.3 From 1b8290db527e29c6b503cb036bc42d67368f766c Mon Sep 17 00:00:00 2001 From: Guillermo Iguaran Date: Fri, 2 Sep 2011 17:10:11 -0500 Subject: Fix asset_path example in CSS and ERB section --- 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 ef35d1ed76..82aa0a5256 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -147,7 +147,7 @@ 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: -.class { background-image: <%= asset_path 'image.png' %> } +.class { background-image: url(<%= asset_path 'image.png') %> } 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. -- cgit v1.2.3 From 5912ed99029f76b3ec51955f05323b77fa0b22f2 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sat, 3 Sep 2011 01:36:57 +0200 Subject: fixes CSS example in the asset pipeline guide --- 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 192c393dca..6935533f4a 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -147,7 +147,7 @@ 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: -.class { background-image: <%= asset_path 'image.png' %> } +.class { background-image: url(<%= asset_path 'image.png' %>) } 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. -- cgit v1.2.3 From a6bafb327d403361ef652d6749f0609cfc2a5578 Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Sun, 4 Sep 2011 18:49:16 +0530 Subject: minor fixes in assets guide --- railties/guides/source/asset_pipeline.textile | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 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 82aa0a5256..f287bcd511 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -15,11 +15,11 @@ 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, 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. +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 Action Pack which depends on the +sprockets+ gem, by default. 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. -In new Rails 3.1 application the asset pipeline is enabled by default. It can be disabled in +application.rb+ by putting this line inside the +Application+ class definition: +In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in +application.rb+ by putting this line inside the +Application+ class definition: config.assets.enabled = false @@ -308,7 +308,7 @@ NOTE: Under normal circumstances the default option should not be changed. If th h4. Precompiling Assets -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 asset manifests and other files in the pipeline to the disk. Compiled assets are written to the location specified in +config.assets.prefix+. The default setting will use the +public/assets+ directory. @@ -361,7 +361,7 @@ This can be changed with the +config.assets.manifest+ option. A fully specified 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. +NOTE: If there are missing precompiled files in production you will get an AssetNoPrecompiledError exception indicating the name of the missing file(s). h5. Server Configuration @@ -385,7 +385,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 disk. 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: @@ -419,7 +419,7 @@ location ~ ^/(assets)/ { 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. +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 option set: @@ -445,7 +445,7 @@ The following line enables YUI compression, and requires the +yui-compressor+ ge config.assets.css_compressor = :yui -The +config.assets.compress+ must be set to +true+ to enable CSS compression +The +config.assets.compress+ must be set to +true+ to enable CSS compression. h4. JavaScript Compression @@ -539,8 +539,7 @@ config.assets.enabled = true config.assets.version = '1.0' # Change the path that assets are served from -# config.assets.prefix = "/assets" - +# config.assets.prefix = "/assets" In +development.rb+: @@ -584,9 +583,8 @@ 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 'sass-rails', "~> 3.1.0" gem 'coffee-rails', "~> 3.1.0" gem 'uglifier' end - -- cgit v1.2.3 From 3e62235c6c384775c0a12ba5683eba37fee8acd9 Mon Sep 17 00:00:00 2001 From: Guillermo Iguaran Date: Sun, 4 Sep 2011 20:56:47 -0500 Subject: Add JavaScript and ERB section to Asset Guide --- railties/guides/source/asset_pipeline.textile | 12 ++++++++++++ 1 file changed, 12 insertions(+) (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 54464cdf4d..69b8d43f55 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -174,6 +174,18 @@ The more generic form can also be used but the asset path and class must both be * +asset-url("rails.png", image)+ becomes +url(/assets/rails.png)+ * +asset-path("rails.png", image)+ becomes +"/assets/rails.png"+ +h5. JavaScript and ERB + +If you add an +erb+ extension to a JavaScript asset, making it something such as +application.js.erb+, then you can use the +asset_path+ helper in your JavaScript code: + + +$('#logo').attr({ + src: "<%= asset_path('logo.png') %>" +}); + + +This writes the path to the particular asset being referenced. + h4. Manifest Files and Directives Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ -- instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets loads the files specified, processes them if necessary, concatenates them into one single file and then compresses them (if +Rails.application.config.assets.compress+ is set to +true+). By serving one file rather than many, the load time of pages are greatly reduced as there are fewer requests to make. -- cgit v1.2.3 From a1dbd94b60ee4118e4706f7bb3a416fcc215e0b5 Mon Sep 17 00:00:00 2001 From: Guillermo Iguaran Date: Sun, 4 Sep 2011 21:01:04 -0500 Subject: Add CoffeeScript example to JavaScript and ERB section --- railties/guides/source/asset_pipeline.textile | 8 +++++++- 1 file changed, 7 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 69b8d43f55..fdb18651dc 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -174,7 +174,7 @@ The more generic form can also be used but the asset path and class must both be * +asset-url("rails.png", image)+ becomes +url(/assets/rails.png)+ * +asset-path("rails.png", image)+ becomes +"/assets/rails.png"+ -h5. JavaScript and ERB +h5. JavaScript/CoffeeScript and ERB If you add an +erb+ extension to a JavaScript asset, making it something such as +application.js.erb+, then you can use the +asset_path+ helper in your JavaScript code: @@ -186,6 +186,12 @@ $('#logo').attr({ This writes the path to the particular asset being referenced. +Similary, you can use the asset_path helper in CoffeeScript files with +erb+ extension (Eg. application.js.coffee.erb): + + +$('#logo').attr src: "<% asset_path('logo.png') %>" + + h4. Manifest Files and Directives Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ -- instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets loads the files specified, processes them if necessary, concatenates them into one single file and then compresses them (if +Rails.application.config.assets.compress+ is set to +true+). By serving one file rather than many, the load time of pages are greatly reduced as there are fewer requests to make. -- cgit v1.2.3 From 8df4fb1bb4e5109f734f396625efd8446253fbd4 Mon Sep 17 00:00:00 2001 From: Guillermo Iguaran Date: Sun, 4 Sep 2011 21:17:23 -0500 Subject: Add reference about "bundle install --without assets" in Precompiling Assets section. --- railties/guides/source/asset_pipeline.textile | 2 ++ 1 file changed, 2 insertions(+) (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 fdb18651dc..1b2e81dc8b 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -348,6 +348,8 @@ This links the folder specified in +config.assets.prefix+ to +shared/assets+. If 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. +Note: If you are precompiling your assets locally you can use +bundle install --without assets+ when installing the gems on the server to avoid install of the assets gems (the gems in the assets group in the Gemfile). + The default matcher for compiling files includes +application.js+, +application.css+ and all files that do not end in +js+ or +css+: -- cgit v1.2.3 From 9584e15d3967a9fd4b38dca26db2de68add96dd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?U=C4=A3is=20Ozols?= Date: Tue, 6 Sep 2011 17:13:30 +0300 Subject: Change hyphen to underscore. --- 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 1b2e81dc8b..1448776c25 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -166,13 +166,13 @@ 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. -* +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"+ h5. JavaScript/CoffeeScript and ERB -- cgit v1.2.3 From 5e2bf4de62014820798b271e97fa010ddc1a7e02 Mon Sep 17 00:00:00 2001 From: Marcus Ilgner Date: Tue, 6 Sep 2011 16:27:26 +0200 Subject: Fixed Apache configuration for gzipped assets: FilesMatch and LocationMatch cannot be nested. --- railties/guides/source/asset_pipeline.textile | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 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 1448776c25..e4f1e0c41a 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -414,16 +414,16 @@ 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 - - - - ForceType text/javascript - + +# without these, Content-Type will be "application/x-gzip" + + ForceType text/css + + + + ForceType text/javascript + For nginx: -- cgit v1.2.3 From 198092e2c0a703ca983893aa4527317b3442b5b1 Mon Sep 17 00:00:00 2001 From: Ryan Walker Date: Tue, 6 Sep 2011 14:06:34 -0300 Subject: Added note about adding a javascript runtime to Gemfile for production environment. --- railties/guides/source/asset_pipeline.textile | 8 ++++++++ 1 file changed, 8 insertions(+) (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 e4f1e0c41a..b6f8d607b9 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -608,3 +608,11 @@ group :assets do gem 'uglifier' end + +Rails 3.1 requires "execjs":https://github.com/sstephenson/execjs - but it doesn't provide a default javascript runtime. When deploying a production app to a system without a pre-existing javascript runtime, you may want to add: + + +group :production do + gem 'therubyracer' +end + -- cgit v1.2.3 From 760fd1eb42038a64591036fc5d687afc98f272aa Mon Sep 17 00:00:00 2001 From: Joost Baaij Date: Wed, 7 Sep 2011 16:09:56 +0300 Subject: Rails.root is a Pathname, no need to use File.join first. --- 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 b6f8d607b9..f2b93be35f 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -112,7 +112,7 @@ All subdirectories that exist within these three locations are added to the sear 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') +config.assets.paths << Rails.root.join('app', 'assets', 'flash') h4. Coding Links to Assets -- cgit v1.2.3 From 0fb3aa750f9980d26b1fe386c3f6cc0bd0bc23e5 Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Wed, 7 Sep 2011 22:32:49 +0530 Subject: copy edit assets guide --- railties/guides/source/asset_pipeline.textile | 38 +++++++++++++-------------- 1 file changed, 19 insertions(+), 19 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 f2b93be35f..e5a08bbed5 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -95,7 +95,7 @@ When a scaffold or controller is generated for the application, Rails also gener 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. +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 @@ -164,15 +164,15 @@ Note that the closing tag cannot be of the style +-%>+. 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. +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 and stylesheet. -* +image_url("rails.png")+ becomes +url(/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"+. h5. JavaScript/CoffeeScript and ERB @@ -186,7 +186,7 @@ $('#logo').attr({ This writes the path to the particular asset being referenced. -Similary, you can use the asset_path helper in CoffeeScript files with +erb+ extension (Eg. application.js.coffee.erb): +Similarly, you can use the +asset_path+ helper in CoffeeScript files with +erb+ extension (eg. application.js.coffee.erb): $('#logo').attr src: "<% asset_path('logo.png') %>" @@ -338,7 +338,7 @@ The rake task is: bundle exec rake assets:precompile -Capistrano (v2.8.0+) has a recipe to handle this in deployment. Add the following line to +Capfile+: +Capistrano (v2.8.0 and above) has a recipe to handle this in deployment. Add the following line to +Capfile+: load 'deploy/assets' @@ -348,7 +348,7 @@ This links the folder specified in +config.assets.prefix+ to +shared/assets+. If 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. -Note: If you are precompiling your assets locally you can use +bundle install --without assets+ when installing the gems on the server to avoid install of the assets gems (the gems in the assets group in the Gemfile). +NOTE. If you are precompiling your assets locally, you can use +bundle install --without assets+ on the server to avoid installing the assets gems (the gems in the assets group in the Gemfile). The default matcher for compiling files includes +application.js+, +application.css+ and all files that do not end in +js+ or +css+: @@ -362,7 +362,7 @@ If you have other manifests or individual stylesheets and JavaScript files to in 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 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: +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. A typical manifest file looks like: --- @@ -451,7 +451,15 @@ On the first request the assets are compiled and cached as outlined in developme 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. +This mode uses more memory, performs poorer than the default and is not recommended. + +When deploying a production application to a system without any pre-existing JavaScript runtimes, you may want to add one to your Gemfile: + + +group :production do + gem 'therubyracer' +end + h3. Customizing the Pipeline @@ -481,7 +489,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 @@ -608,11 +616,3 @@ group :assets do gem 'uglifier' end - -Rails 3.1 requires "execjs":https://github.com/sstephenson/execjs - but it doesn't provide a default javascript runtime. When deploying a production app to a system without a pre-existing javascript runtime, you may want to add: - - -group :production do - gem 'therubyracer' -end - -- cgit v1.2.3 From 190a2bf9c482fef8412982ea31a755d7e59f17b6 Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Wed, 7 Sep 2011 22:33:04 +0530 Subject: Revert "Rails.root is a Pathname, no need to use File.join first." This reverts commit 760fd1eb42038a64591036fc5d687afc98f272aa. Reason: We need a fully qualified path string here, not a Pathname. --- 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 e5a08bbed5..bad1c08747 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -112,7 +112,7 @@ All subdirectories that exist within these three locations are added to the sear You can add additional (fully qualified) paths to the pipeline in +application.rb+. For example: -config.assets.paths << Rails.root.join('app', 'assets', 'flash') +config.assets.paths << File.join(Rails.root, 'app', 'assets', 'flash') h4. Coding Links to Assets -- cgit v1.2.3 From 59198ecb657763b4fbaee84b47a74ebb99b3e54c Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Thu, 8 Sep 2011 18:25:43 +0530 Subject: some copy-edits --- railties/guides/source/asset_pipeline.textile | 4 ++-- 1 file changed, 2 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 bad1c08747..ba48a2196b 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -415,12 +415,12 @@ For Apache: RewriteCond %{REQUEST_FILENAME}.gz -s RewriteRule ^(.+) $1.gz [L] - + # without these, Content-Type will be "application/x-gzip" ForceType text/css - + ForceType text/javascript -- cgit v1.2.3 From 22a4f7e8bd3c70067824945881a61820aad7aff6 Mon Sep 17 00:00:00 2001 From: Emin Hasanov Date: Sun, 11 Sep 2011 14:18:07 +0600 Subject: Fix typo in "must-revalidate" header name --- 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 ba48a2196b..211b02b94b 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -282,7 +282,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-revalidate+ 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. -- cgit v1.2.3 From bde113a82e792ef3480d686a1e66fea56c76c46d Mon Sep 17 00:00:00 2001 From: Jaime Iniesta Date: Wed, 14 Sep 2011 00:09:59 +0200 Subject: Fix typos and broken link on asset pipeline guide --- 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 211b02b94b..31a1aeee15 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -63,7 +63,7 @@ This has several disadvantages:
  1. 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. + "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 this case 5-20% of requests will not be cached.
  2. The file name can change between nodes in multi-server environments.
    @@ -132,7 +132,7 @@ In regular views you can access images in the +assets/images+ directory like thi 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. -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. +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 "In Production":#in-production section later on in this guide. 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. @@ -537,7 +537,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 development and production. +Sprockets uses the default Rails cache store to cache assets in development and production. TODO: Add more about changing the default store. -- cgit v1.2.3 From b3ff720567b41ca5db9e6956c37cc0792b7a3f4e Mon Sep 17 00:00:00 2001 From: Ben Walding Date: Wed, 14 Sep 2011 15:27:38 +1000 Subject: Add equivalent nginx configuration --- railties/guides/source/asset_pipeline.textile | 16 +++++++++++++++- 1 file changed, 15 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 31a1aeee15..ce4eafb97c 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -403,7 +403,21 @@ For Apache: -TODO: nginx instructions +For nginx: + + +location ~ ^/assets/ { + expires 1y; + add_header Cache-Control public; + + # Some browsers still send conditional-GET requests if there's a + # Last-Modified header or an ETag header even if they haven't + # reached the expiry date sent in the Expires header. + add_header Last-Modified ""; + add_header ETag ""; + break; +} + 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 disk. 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: -- cgit v1.2.3 From 28677014a4f8121272a17870246507e86e46837c Mon Sep 17 00:00:00 2001 From: Guillermo Iguaran Date: Thu, 15 Sep 2011 20:07:01 -0500 Subject: Add reference about --skip-sprockets to Asset Pipeline Guide --- railties/guides/source/asset_pipeline.textile | 6 ++++++ 1 file changed, 6 insertions(+) (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 ce4eafb97c..74dfdfb540 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -25,6 +25,12 @@ In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in +a config.assets.enabled = false +You can also disable it when you are creating a new application passing the --skip-sprockets parameter: + + +rails new appname --skip-sprockets + + It is recommended that you use the defaults for all new apps. -- cgit v1.2.3 From 8411f631c42de7d6f51d10d997b037b9eff0d1f1 Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Fri, 16 Sep 2011 23:22:03 +0530 Subject: minor edit --- 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 74dfdfb540..bea5e494d5 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -25,7 +25,7 @@ In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in +a config.assets.enabled = false -You can also disable it when you are creating a new application passing the --skip-sprockets parameter: +You can also disable it while creating a new application by passing the --skip-sprockets option. rails new appname --skip-sprockets -- cgit v1.2.3 From 27f1320fde03279c575693f504897f1a6171bc59 Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Fri, 16 Sep 2011 22:12:41 +0530 Subject: Fixing incorrect notextile tags --- 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 bea5e494d5..e03ae736a8 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -359,7 +359,7 @@ NOTE. If you are precompiling your assets locally, you can use +bundle install - The default matcher for compiling files includes +application.js+, +application.css+ and all files that do not end in +js+ or +css+: -[ /\w+\.(?!js|css).+/, /application.(css|js)$/ ] +[ /\w\.(?!js|css)./, /application.(css|js)$/ ] If you have other manifests or individual stylesheets and JavaScript files to include, you can add them to the +precompile+ array: -- cgit v1.2.3 From 663031801cac577a88931cdfe6f062555112f370 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?U=C4=A3is=20Ozols?= Date: Sat, 17 Sep 2011 10:00:53 +0300 Subject: sass-rails helpers - hyphenated in Sass, underscored in Ruby. --- 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 e03ae736a8..586a9f46eb 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -170,15 +170,15 @@ Note that the closing tag cannot be of the style +-%>+. 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 and stylesheet. +When using the asset pipeline, paths to assets must be re-written and +sass-rails+ provides +-url+ and +-path+ helpers (hyphenated in Sass, underscored in Ruby) for the following asset classes: image, font, video, audio, JavaScript and 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"+ h5. JavaScript/CoffeeScript and ERB -- cgit v1.2.3 From 94ed1e24956c5d6d3482517d10134938d37e837d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Hock=20Isaza?= Date: Mon, 26 Sep 2011 16:34:42 -0500 Subject: Alert about the new Bundler require for asset gems If you are coming from a Rails 3.0 application, you won't have the correct Bundler require statement. This will cause the gems under the `assets` group not to be available in the development and production environment. I think this is related to the issue #39 in rails-sass https://github.com/rails/sass-rails/issues/39 --- railties/guides/source/asset_pipeline.textile | 21 ++++++++++++++++++++- 1 file changed, 20 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 586a9f46eb..3428c09bcd 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -247,9 +247,9 @@ h4. Preprocessing 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 a +app/assets/stylesheets/projects.css.scss+ file. When these files are requested, they are processed by the processors provided by the +coffee-script+ and +sass-rails+ gems and then sent back to the browser as JavaScript and CSS respectively. - Additional layers of pre-processing 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, 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, CoffeeScript and served as JavaScript. + Keep in mind that the order of these pre-processors is important. For example, if you called your JavaScript file +app/assets/javascripts/projects.js.erb.coffee+ then it is processed with the CoffeeScript interpreter first, which wouldn't understand ERB and therefore you would run into problems. h3. In Development @@ -636,3 +636,22 @@ group :assets do gem 'uglifier' end + +If you use the +assets+ group with Bundler, please make sure that your +config/application.rb+ has the following Bundler require statement. + + +if defined?(Bundler) + # If you precompile assets before deploying to production, use this line + Bundler.require *Rails.groups(:assets => %w(development test)) + # If you want your assets lazily compiled in production, use this line + # Bundler.require(:default, :assets, Rails.env) +end + + +Instead of the old Rails 3.0 one + + +# If you have a Gemfile, require the gems listed there, including any gems +# you've limited to :test, :development, or :production. +Bundler.require(:default, Rails.env) if defined?(Bundler) + \ No newline at end of file -- cgit v1.2.3 From 01e5e2faebb4a8082d38eb585762dc16ce3698f7 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Mon, 26 Sep 2011 18:18:52 -0700 Subject: partial pass over the asset pipeline guide --- railties/guides/source/asset_pipeline.textile | 42 ++++++++++++++------------- 1 file changed, 22 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 586a9f46eb..c0694dda4e 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -17,13 +17,13 @@ The asset pipeline provides a framework to concatenate and minify or compress Ja 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 Action Pack which depends on the +sprockets+ gem, by default. -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. +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 keynote at RailsConf 2011. -In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in +application.rb+ by putting this line inside the +Application+ class definition: +In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in +config/application.rb+ by putting this line inside the application class definition: - + config.assets.enabled = false - + You can also disable it while creating a new application by passing the --skip-sprockets option. @@ -36,7 +36,9 @@ It is recommended that you use the defaults for all new apps. h4. Main Features -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. +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+ --, it has a series of limitations. For example, it cannot generate the caches in advance, and it is not able to transparently include assets provided by third-party libraries. The default behavior in Rails 3.1 and onward is to concatenate all files into one master file each for JS and CSS. However, you can separate files or groups of files if required (see below). In production, an MD5 fingerprint is inserted into each filename so that the file is cached by the web browser but can be invalidated if the fingerprint is altered. @@ -46,14 +48,14 @@ The third feature is the ability to code these assets using another language, or h4. What is Fingerprinting and Why Should I Care? -Fingerprinting is a technique whereby the filenames of content that is static or infrequently updated is altered to be unique to the content contained in the file. +Fingerprinting is a technique whereby the filenames of content that is static or infrequently updated are altered to be unique to the content contained in the file. -When a filename is unique and based on its content, HTTP headers can be set to encourage caches everywhere (at ISPs, in browsers) to keep their own copy of the content. When the content is updated, the fingerprint will change and the remote clients will request the new file. This is generally known as _cachebusting_. +When a filename is unique and based on its content, HTTP headers can be set to encourage caches everywhere (at ISPs, in browsers) to keep their own copy of the content. When the content is updated, the fingerprint will change and the remote clients will request the new file. This is generally known as _cache busting_. -The most effective technique is to insert a hash of the content into the name, usually at the end. For example a CSS file +global.css+ is hashed and the filename is updated to incorporate the hash. +The most effective technique is to insert a hash of the content into the name, usually at the end. For example a CSS file +global.css+ is hashed and the filename is updated to incorporate the digest, for example becoming: -global.css => global-908e25f4bf641868d8683022a5b62f54.css +global-908e25f4bf641868d8683022a5b62f54.css This is the strategy adopted by the Rails asset pipeline. @@ -68,8 +70,8 @@ This has several disadvantages:
    1. - 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 this case 5-20% of requests will not be cached. + 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 this case 5-20% of requests will not be cached. Query strings in particular do not work at all with some CDNs for cache invalidation.
    2. The file name can change between nodes in multi-server environments.
      @@ -77,9 +79,9 @@ This has several disadvantages:
    -The other problem is that when static assets are deployed with each new release of code, the mtime of *all* these files changes, forcing all remote clients to fetch them again, even when the content of those assets has not changed. +The other problem is that when static assets are deployed with each new release of code, the mtime of _all_ these files changes, forcing all remote clients to fetch them again, even when the content of those assets has not changed. -Fingerprinting avoids all these problems by ensuring filenames are consistent based on their content. +Fingerprinting fixes these problems by avoiding query strings, and by ensuring filenames are consistent based on their content. 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. @@ -95,7 +97,7 @@ 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. +In production, the default is to precompile these files to +public/assets+ so that they can be more efficiently delivered by the web server. 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. @@ -115,11 +117,11 @@ 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: +You can add additional (fully qualified) paths to the pipeline in +config/application.rb+. For example: - -config.assets.paths << File.join(Rails.root, 'app', 'assets', 'flash') - + +config.assets.paths << "#{Rails.root}/app/assets/flash" + h4. Coding Links to Assets @@ -150,10 +152,10 @@ Images can also be organized into subdirectories if required, and they can be ac 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: +If you add an +erb+ extension to a CSS asset, making it something such as +application.css.erb+, then helpers like +image_path+ are available in your CSS rules: -.class { background-image: url(<%= asset_path 'image.png' %>) } +.class { background-image: url(<%= image_path 'image.png' %>) } 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. -- cgit v1.2.3 From c612183ad19f2c11eb58e4393a759a1016ce4c05 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Tue, 27 Sep 2011 13:50:49 -0700 Subject: partial pass over the asset pipeline --- railties/guides/source/asset_pipeline.textile | 31 +++++++++++++++------------ 1 file changed, 17 insertions(+), 14 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 b343e8d01d..c5bbe3226a 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -152,15 +152,15 @@ Images can also be organized into subdirectories if required, and they can be ac h5. CSS and ERB -If you add an +erb+ extension to a CSS asset, making it something such as +application.css.erb+, then helpers like +image_path+ are available in your CSS rules: +If you add an +erb+ extension to a CSS asset, making it something such as +application.css.erb+, then helpers like +asset_path+ are available in your CSS rules: -.class { background-image: url(<%= image_path 'image.png' %>) } +.class { background-image: url(<%= asset_path 'image.png' %>) } 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. +If you want to use a "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' %>) } @@ -186,27 +186,28 @@ h5. JavaScript/CoffeeScript and ERB If you add an +erb+ extension to a JavaScript asset, making it something such as +application.js.erb+, then you can use the +asset_path+ helper in your JavaScript code: - + $('#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 (eg. application.js.coffee.erb): +Similarly, you can use the +asset_path+ helper in CoffeeScript files with +erb+ extension (eg. +application.js.coffee.erb+): -$('#logo').attr src: "<% asset_path('logo.png') %>" +$('#logo').attr src: "<%= asset_path('logo.png') %>" h4. Manifest Files and Directives -Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ -- instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets loads the files specified, processes them if necessary, concatenates them into one single file and then compresses them (if +Rails.application.config.assets.compress+ is set to +true+). By serving one file rather than many, the load time of pages are greatly reduced as there are fewer requests to make. +Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ -- instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets loads the files specified, processes them if necessary, concatenates them into one single file and then compresses them (if +Rails.application.config.assets.compress+ is true). By serving one file rather than many, the load time of pages are greatly reduced as there are fewer requests to make. For example, in the default Rails application there's a +app/assets/javascripts/application.js+ file which contains the following lines: +// ... //= require jquery //= require jquery_ujs //= require_tree . @@ -214,9 +215,11 @@ For example, in the default Rails application there's a +app/assets/javascripts/ In JavaScript files, the directives begin with +//=+. In this case, the file is using the +require+ and the +require_tree+ directives. The +require+ directive is used to tell Sprockets the files that you wish to require. Here, you are requiring the files +jquery.js+ and +jquery_ujs.js+ that are available somewhere in the search path for Sprockets. You need not supply the extensions explicitly. Sprockets assumes you are requiring a +.js+ file when done from within a +.js+ file. -NOTE. In Rails 3.1, the +jquery.js+ and +jquery_ujs.js+ files are located inside the +vendor/assets/javascripts+ directory contained within the +jquery-rails+ gem. +NOTE. In Rails 3.1 the +jquery-rails+ gem provides the +jquery.js+ and +jquery_ujs.js+ files via the asset pipeline. You won't see them in the application tree. + +The +require_tree+ directive tells Sprockets to recursively include _all_ JavaScript files in this directory into the output. Only a path relative to the manifest file can be specified. There is also a +require_directory+ directive which includes all JavaScript files only in the directory specified (no nesting). -The +require_tree .+ directive tells Sprockets to include _all_ JavaScript files in this directory into the output. Only a path relative to the file can be specified. There is also a +require_directory+ directive which includes all JavaScript files only in the directory specified (no nesting). +Directives are processed top to bottom, but the order in which files are included by +require_tree+ is unespecified. You should not rely on any particular among those. If you need to ensure some particular JavaScript ends up above some other, require it before in the manifest. Note that the family of +require+ directives prevents files from being included twice in the output. There's also a default +app/assets/stylesheets/application.css+ file which contains these lines: @@ -233,7 +236,7 @@ In this example +require_self+ is used. This puts the CSS contained within the f You can have as many manifest files as you need. For example the +admin.css+ and +admin.js+ manifest could contain the JS and CSS files that are used for the admin section of an application. -For some assets (like CSS) the compiled order is important. You can specify individual files and they are compiled in the order specified: +The same remarks about ordering made above apply. In particular, you can specify individual files and they are compiled in the order specified: /* ... @@ -246,13 +249,13 @@ For some assets (like CSS) the compiled order is important. You can specify indi h4. Preprocessing -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 a +app/assets/stylesheets/projects.css.scss+ file. +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. When these files are requested, they are processed by the processors provided by the +coffee-script+ and +sass-rails+ gems and then sent back to the browser as JavaScript and CSS respectively. -Additional layers of pre-processing 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, 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, CoffeeScript and served as JavaScript. +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, 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, CoffeeScript, and served as JavaScript. -Keep in mind that the order of these pre-processors is important. For example, if you called your JavaScript file +app/assets/javascripts/projects.js.erb.coffee+ then it is processed with the CoffeeScript interpreter first, which wouldn't understand ERB and therefore you would run into problems. +Keep in mind that the order of these preprocessors is important. For example, if you called your JavaScript file +app/assets/javascripts/projects.js.erb.coffee+ then it would be processed with the CoffeeScript interpreter first, which wouldn't understand ERB and therefore you would run into problems. h3. In Development -- cgit v1.2.3 From 41c8277a9b04dda40972bbafa2dbfc00c5c238fb Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Tue, 27 Sep 2011 13:55:41 -0700 Subject: the infamous detail only spotted in GitHub diffs no matter how careful you were before pushing --- 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 c5bbe3226a..8a15618eb2 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -219,7 +219,7 @@ NOTE. In Rails 3.1 the +jquery-rails+ gem provides the +jquery.js+ and +jquery_u The +require_tree+ directive tells Sprockets to recursively include _all_ JavaScript files in this directory into the output. Only a path relative to the manifest file can be specified. There is also a +require_directory+ directive which includes all JavaScript files only in the directory specified (no nesting). -Directives are processed top to bottom, but the order in which files are included by +require_tree+ is unespecified. You should not rely on any particular among those. If you need to ensure some particular JavaScript ends up above some other, require it before in the manifest. Note that the family of +require+ directives prevents files from being included twice in the output. +Directives are processed top to bottom, but the order in which files are included by +require_tree+ is unespecified. You should not rely on any particular order among those. If you need to ensure some particular JavaScript ends up above some other, require it before in the manifest. Note that the family of +require+ directives prevents files from being included twice in the output. There's also a default +app/assets/stylesheets/application.css+ file which contains these lines: -- cgit v1.2.3 From f3b8cd9d364934795ee4ec63a2d8852b3dde1aa8 Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Wed, 28 Sep 2011 13:35:46 +0530 Subject: fixing typo in assets guide --- 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 8a15618eb2..152f42f4eb 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -219,7 +219,7 @@ NOTE. In Rails 3.1 the +jquery-rails+ gem provides the +jquery.js+ and +jquery_u The +require_tree+ directive tells Sprockets to recursively include _all_ JavaScript files in this directory into the output. Only a path relative to the manifest file can be specified. There is also a +require_directory+ directive which includes all JavaScript files only in the directory specified (no nesting). -Directives are processed top to bottom, but the order in which files are included by +require_tree+ is unespecified. You should not rely on any particular order among those. If you need to ensure some particular JavaScript ends up above some other, require it before in the manifest. Note that the family of +require+ directives prevents files from being included twice in the output. +Directives are processed top to bottom, but the order in which files are included by +require_tree+ is unspecified. You should not rely on any particular order among those. If you need to ensure some particular JavaScript ends up above some other, require it before in the manifest. Note that the family of +require+ directives prevents files from being included twice in the output. There's also a default +app/assets/stylesheets/application.css+ file which contains these lines: -- cgit v1.2.3 From cba3c00831a7c5bb25bc785e856984705ca2077c Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Wed, 28 Sep 2011 13:48:23 -0700 Subject: partial pass over the assets guide --- railties/guides/source/asset_pipeline.textile | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 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 152f42f4eb..a0af018d30 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -261,7 +261,7 @@ h3. In Development In development mode assets are served as separate files in the order they are specified in the manifest file. -This manifest +application.js+: +This manifest +app/assets/javascripts/application.js+: //= require core @@ -272,45 +272,42 @@ 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: +You can turn off debug mode by updating +config/environments/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: +When debug mode is off Sprockets concatenates and runs the necessary preprocessors on all files. With debug mode turned off the manifest above would generate instead: - + -Assets are compiled and cached on the first request after the server is started. Sprockets sets a +must-revalidate+ 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-revalidate+ 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 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: +Debug mode can also be enabled in the Rails helper methods: <%= stylesheet_link_tag "application", :debug => true %> <%= javascript_include_tag "application", :debug => true %> -The +:debug+ option is ignored if the debug mode is off. +The +:debug+ option is redundant if debug mode is on. You could potentially also enable compression in development mode as a sanity check, and disable it on-demand as required for debugging. - h3. In Production 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. -- cgit v1.2.3 From 6e00c05607c03eead00966a5de4769b2e77af196 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sun, 2 Oct 2011 11:35:41 -0700 Subject: documents config.assets.initialize_on_precompile in the asset pipeline guide --- railties/guides/source/asset_pipeline.textile | 7 +++++++ 1 file changed, 7 insertions(+) (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 a0af018d30..da0ffb80d2 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -346,6 +346,13 @@ The rake task is: bundle exec rake assets:precompile +Asset templates in general have access to application objects. You may prevent application +initialization in precompilation setting +config.assets.initialize_on_precompile+ to false. + +WARNING: Application objects may still be in scope in asset templates in develoment mode. +If +config.assets.initialize_on_precompile+ is set to false it is your responsability not +to use them at all. + Capistrano (v2.8.0 and above) has a recipe to handle this in deployment. Add the following line to +Capfile+: -- cgit v1.2.3 From ac1fc5c59499db8d3e875bbd76e0b7c2c9240089 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sun, 2 Oct 2011 12:33:14 -0700 Subject: rewords the docs of config.assets.initialize_on_precompile in the asset pipeline guide --- railties/guides/source/asset_pipeline.textile | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 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 da0ffb80d2..7795b297f3 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -346,12 +346,14 @@ The rake task is: bundle exec rake assets:precompile -Asset templates in general have access to application objects. You may prevent application -initialization in precompilation setting +config.assets.initialize_on_precompile+ to false. - -WARNING: Application objects may still be in scope in asset templates in develoment mode. -If +config.assets.initialize_on_precompile+ is set to false it is your responsability not -to use them at all. +For faster asset precompiles, you can partially load your application by setting ++config.assets.initialize_on_precompile+ to false, though in that case templates +cannot see application objects or methods. *Heroku requires this to be false.* + +WARNING: If you set +config.assets.initialize_on_precompile+ to false, be sure to +test +rake assets:precompile+ locally before deploying. It may expose bugs where +your assets reference application objects or methods, since those are still +in scope in development mode regardless of the value of this flag. Capistrano (v2.8.0 and above) has a recipe to handle this in deployment. Add the following line to +Capfile+: -- cgit v1.2.3 From 3d595c5eaeec43e5dc9f2930420506108b0ce813 Mon Sep 17 00:00:00 2001 From: Nick Quaranto Date: Wed, 5 Oct 2011 22:27:33 -0400 Subject: use Rails.root.join for assets guide --- 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 7795b297f3..ccbc737f17 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -120,7 +120,7 @@ All subdirectories that exist within these three locations are added to the sear You can add additional (fully qualified) paths to the pipeline in +config/application.rb+. For example: -config.assets.paths << "#{Rails.root}/app/assets/flash" +config.assets.paths << Rails.root.join("app", "assets", "flash") h4. Coding Links to Assets -- cgit v1.2.3 From 9d091c038d5e3d35be09fbd0fd1603e3a4035ac2 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Thu, 6 Oct 2011 16:22:40 +0200 Subject: revises the precompilation section of the asset pipeline guide (web server configuration for gzipped assets pending) --- 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 7795b297f3..7c79b202f1 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -398,7 +398,7 @@ This can be changed with the +config.assets.manifest+ option. A fully specified 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(s). +NOTE: If there are missing precompiled files in production you will get an Sprockets::Helpers::RailsHelper:: AssetPaths::AssetNotPrecompiledError exception indicating the name of the missing file(s). h5. Server Configuration @@ -436,9 +436,9 @@ location ~ ^/assets/ { } -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 disk. 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 "gzipped":http://en.wikipedia.org/wiki/Gzip (.gz) version of your assets. Web servers are typically configured to use a moderate compression ratio as a compromise, but since precompilation happens once Sprockets uses the maximum compression ratio, thus reducing the size of the data transfer to the minimum. One the other hand, web servers can be configured to serve compressed content directly from disk, rather than deflating non-compressed files themselves. -For Apache: +A possible configuration for Apache could be: -- cgit v1.2.3 From 2224a06b72d77343acd2cb82ec27cb02c6ec6df6 Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Thu, 6 Oct 2011 20:04:09 +0530 Subject: fix a space in the assets guide --- 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 7c79b202f1..1b06f4dedb 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -398,7 +398,7 @@ This can be changed with the +config.assets.manifest+ option. A fully specified config.assets.manifest = '/path/to/some/other/location' -NOTE: If there are missing precompiled files in production you will get an Sprockets::Helpers::RailsHelper:: AssetPaths::AssetNotPrecompiledError exception indicating the name of the missing file(s). +NOTE: If there are missing precompiled files in production you will get an Sprockets::Helpers::RailsHelper::AssetPaths::AssetNotPrecompiledError exception indicating the name of the missing file(s). h5. Server Configuration -- cgit v1.2.3 From 0549ba10b30dc2b4d669f53359b67dd17c2ca6a6 Mon Sep 17 00:00:00 2001 From: clay shentrup Date: Thu, 6 Oct 2011 16:09:36 -0700 Subject: Clarifying ambiguous description of require_self in the asset pipeline --- 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 ccbc737f17..acf7495267 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -232,7 +232,7 @@ There's also a default +app/assets/stylesheets/application.css+ file which conta The directives that work in the JavaScript files also work in stylesheets, obviously including stylesheets rather than JavaScript files. The +require_tree+ directive here works the same way as the JavaScript one, requiring all stylesheets from the current directory. -In this example +require_self+ is used. This puts the CSS contained within the file (if any) at the top of any other CSS in this file unless +require_self+ is specified after another +require+ directive. +In this example +require_self+ is used. This puts the CSS contained within the file (if any) at the precise location of the +require_self+ call. If +require_self+ is called more than once, only the last call is respected. You can have as many manifest files as you need. For example the +admin.css+ and +admin.js+ manifest could contain the JS and CSS files that are used for the admin section of an application. -- cgit v1.2.3 From b1c20e37eccdfab7bb94d34f249c5e49256b9980 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Fri, 7 Oct 2011 15:05:14 +0200 Subject: asset pipeline guide: removes Apache config for serving pre-compressed assets, and expands the information about nginx support for this A robust Apache configuration for this feature seems to be tricky, one that takes into account Accept-Encoding, sets Vary, ensures Content-Type is right, etc. --- railties/guides/source/asset_pipeline.textile | 33 ++++++++++----------------- 1 file changed, 12 insertions(+), 21 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 1b06f4dedb..f2eade6bc6 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -438,36 +438,27 @@ location ~ ^/assets/ { When files are precompiled, Sprockets also creates a "gzipped":http://en.wikipedia.org/wiki/Gzip (.gz) version of your assets. Web servers are typically configured to use a moderate compression ratio as a compromise, but since precompilation happens once Sprockets uses the maximum compression ratio, thus reducing the size of the data transfer to the minimum. One the other hand, web servers can be configured to serve compressed content directly from disk, rather than deflating non-compressed files themselves. -A possible configuration for Apache could be: - - - - # 2 lines to serve pre-gzipped version - RewriteCond %{REQUEST_FILENAME}.gz -s - RewriteRule ^(.+) $1.gz [L] - - -# without these, Content-Type will be "application/x-gzip" - - ForceType text/css - - - - ForceType text/javascript - - - -For nginx: +Nginx is able to do this automatically enabling +gzip_static+: location ~ ^/(assets)/ { root /path/to/public; gzip_static on; # to serve pre-gzipped version expires max; - add_header Cache-Control public; + add_header Cache-Control public; } +This directive is available if the core module that provides this feature was compiled with the web server. Ubuntu packages, even +nginx-light+ have the module compiled. Otherwise, you may need to perform a manual compilation: + + +./configure --with-http_gzip_static_module + + +If you're compiling nginx with Phusion Passenger you'll need to pass that option when prompted. + +Unfortunately, a robust configuration for Apache is possible but tricky, please Google around. + 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. -- cgit v1.2.3 From d2db917841cacbdd6320460fd6fa3d07cd972139 Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Sat, 8 Oct 2011 02:20:09 +0530 Subject: fix bad formatting in the assets guide --- 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 ef01cd32ac..df41c7a9e8 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -38,7 +38,7 @@ h4. Main Features 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+ --, it has a series of limitations. For example, it cannot generate the caches in advance, and it is not able to transparently include assets provided by third-party libraries. +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+, it has a series of limitations. For example, it cannot generate the caches in advance, and it is not able to transparently include assets provided by third-party libraries. The default behavior in Rails 3.1 and onward is to concatenate all files into one master file each for JS and CSS. However, you can separate files or groups of files if required (see below). In production, an MD5 fingerprint is inserted into each filename so that the file is cached by the web browser but can be invalidated if the fingerprint is altered. -- cgit v1.2.3 From da773a24beab90236802a2ca39e5b124b1b5d456 Mon Sep 17 00:00:00 2001 From: Roy Tomeij Date: Sun, 9 Oct 2011 13:38:47 +0200 Subject: Add note about how Sass & Sprockets don't match --- 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 ef01cd32ac..303066b752 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -19,7 +19,7 @@ Prior to Rails 3.1 these features were added through third-party Ruby libraries 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 keynote at RailsConf 2011. -In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in +config/application.rb+ by putting this line inside the application class definition: +In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in +config/application.rb+ by publicing this line inside the application class definition: config.assets.enabled = false @@ -234,6 +234,8 @@ The directives that work in the JavaScript files also work in stylesheets, obvio In this example +require_self+ is used. This puts the CSS contained within the file (if any) at the precise location of the +require_self+ call. If +require_self+ is called more than once, only the last call is respected. +NOTE. If you want to use multiple Sass files, use the "Sass +@import+ rule":http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#import instead of the Sprockets directives. Using Sprockets directives all Sass files exist within their own scope, making variables or mixins only available within the document they were defined in. + You can have as many manifest files as you need. For example the +admin.css+ and +admin.js+ manifest could contain the JS and CSS files that are used for the admin section of an application. The same remarks about ordering made above apply. In particular, you can specify individual files and they are compiled in the order specified: -- cgit v1.2.3 From d214e54e7aadd15bbf872c3deae24908258e8cb8 Mon Sep 17 00:00:00 2001 From: Roy Tomeij Date: Sun, 9 Oct 2011 13:45:54 +0200 Subject: Fix a typo that was mysteriously entered in previous commit --- 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 303066b752..1b245b1fc7 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -19,7 +19,7 @@ Prior to Rails 3.1 these features were added through third-party Ruby libraries 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 keynote at RailsConf 2011. -In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in +config/application.rb+ by publicing this line inside the application class definition: +In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in +config/application.rb+ by putting this line inside the application class definition: config.assets.enabled = false -- cgit v1.2.3 From 86919a6da17e164e6bb9e1f355052e552929141e Mon Sep 17 00:00:00 2001 From: Pascal Lindelauf Date: Mon, 17 Oct 2011 14:45:45 +0200 Subject: Clarified that the config.assets.initialize_on_precompile directive needs to be set in application.rb --- 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 afaf0f6fe3..6eb4ae49e3 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -349,7 +349,7 @@ bundle exec rake assets:precompile For faster asset precompiles, you can partially load your application by setting -+config.assets.initialize_on_precompile+ to false, though in that case templates ++config.assets.initialize_on_precompile+ to false in +config/application.rb+, though in that case templates cannot see application objects or methods. *Heroku requires this to be false.* WARNING: If you set +config.assets.initialize_on_precompile+ to false, be sure to -- cgit v1.2.3 From df5f88c7c0fce0d3b7a994ae376e626cd6d47d34 Mon Sep 17 00:00:00 2001 From: Henare Degan Date: Wed, 26 Oct 2011 19:03:53 +1200 Subject: Fix a little typo --- 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 6eb4ae49e3..6ff5e87b6d 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -438,7 +438,7 @@ location ~ ^/assets/ { } -When files are precompiled, Sprockets also creates a "gzipped":http://en.wikipedia.org/wiki/Gzip (.gz) version of your assets. Web servers are typically configured to use a moderate compression ratio as a compromise, but since precompilation happens once Sprockets uses the maximum compression ratio, thus reducing the size of the data transfer to the minimum. One the other hand, web servers can be configured to serve compressed content directly from disk, rather than deflating non-compressed files themselves. +When files are precompiled, Sprockets also creates a "gzipped":http://en.wikipedia.org/wiki/Gzip (.gz) version of your assets. Web servers are typically configured to use a moderate compression ratio as a compromise, but since precompilation happens once Sprockets uses the maximum compression ratio, thus reducing the size of the data transfer to the minimum. On the other hand, web servers can be configured to serve compressed content directly from disk, rather than deflating non-compressed files themselves. Nginx is able to do this automatically enabling +gzip_static+: -- cgit v1.2.3 From bc00514b6236d701d3e660c4ec365a767a070a91 Mon Sep 17 00:00:00 2001 From: rpq Date: Tue, 15 Nov 2011 23:20:21 -0500 Subject: added comma --- 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 6ff5e87b6d..3681501293 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -438,7 +438,7 @@ location ~ ^/assets/ { } -When files are precompiled, Sprockets also creates a "gzipped":http://en.wikipedia.org/wiki/Gzip (.gz) version of your assets. Web servers are typically configured to use a moderate compression ratio as a compromise, but since precompilation happens once Sprockets uses the maximum compression ratio, thus reducing the size of the data transfer to the minimum. On the other hand, web servers can be configured to serve compressed content directly from disk, rather than deflating non-compressed files themselves. +When files are precompiled, Sprockets also creates a "gzipped":http://en.wikipedia.org/wiki/Gzip (.gz) version of your assets. Web servers are typically configured to use a moderate compression ratio as a compromise, but since precompilation happens once, Sprockets uses the maximum compression ratio, thus reducing the size of the data transfer to the minimum. On the other hand, web servers can be configured to serve compressed content directly from disk, rather than deflating non-compressed files themselves. Nginx is able to do this automatically enabling +gzip_static+: -- cgit v1.2.3