- Understanding Spree’s use of the Rails asset pipeline
- Managing application specific assets
- Managing extension specific assets
- Overriding Spree’s core assets
Be sure to read the other customization methods available in the Customization Overview page.
Spree’s Asset Pipeline
A typical assets directory for a Spree application will look like:
How core extensions (engines) manage assets
For example, spree_core provides the following manifests:
//= require admin/spree_auth
//= require admin/spree_api
//= require admin/spree_dash
//= require admin/spree_promo
//= require_tree .
Managing your application’s assets
INFO: Images will be served in development mode, or compiled into the public directory automatically in production mode.
NOTE: When upgrading from previous versions of Spree it’s important that you relocate all assets from the public directory into the relevant app/assets directory.
Managing your extension’s assets
We’re suggesting that all third party extensions should adopt the same approach as spree_core and provide the same four (or less depending on what the extension requires) manifest files, using the same directory structure as outlined above.
Third party extension manifest files will not be automatically included in the relevant all.(js|css) files so it’s important to document the manual inclusion in your extensions installation instructions or provide a Rails generator to do so.
For an example of an extension using a generator to install assets and migrations take a look at the recently added install_generator on the rails3-1 branch of spree_wishlist.
Overriding Spree’s core assets
The methods listed below will work for both applications, extensions and themes with one noticeable difference: Extension & theme asset files will not be automatically included (see above for instructions on how to include asset files from your extensions / themes).
Overriding individual CSS styles
Say for example you want to replace the following CSS snippet:
/* app/assets/stylesheets/store/screen.css */
You can now just create a new stylesheet inside your_app/app/assets/stylesheets/store/ and include the following CSS:
/* app/assets/stylesheets/store/foo.css */
border: 1px solid red;
The store/all.css manifest will automatically include foo.css and it will actually include both definitions with the one from foo.css being included last, hence it will be the rule applied.
Overriding entire CSS files
To replace an entire stylesheet as provided by Spree you simply need to create a file with the same name and save it to the corresponding path within your application’s or extension’s app/assets/stylesheets directory.
For example, to replace store/all.css you would save the replacement to your_app/app/assets/stylesheets/store/all.css.
NOTE: This same method can be used to override stylesheets provided by third-party extensions.
The resulting store/all.js would include both methods, with the latter being the one executed on request.
Finally, images can be replaced by substituting the required file into the same path within your application or extension as the file you would like to replace.
For example, to replace the Spree logo you would simply copy your logo to: your_app/app/assets/images/admin/bg/spree_50.png.