1. Deface
    1. Available actions
      1. :remove – Removes all elements that match the supplied selector
      2. :replace – Replaces all elements that match the supplied selector, with the content supplied.
      3. :insert_after – Inserts content supplied after all elements that match the supplied selector
      4. :insert_before – Inserts content supplied before all elements that match the supplied selector
      5. :insert_top – Inserts content supplied inside all elements that match the supplied selector, as the first child.
      6. :insert_bottom – Inserts content supplied inside all elements that match the supplied selector, as the last child.
    2. Supplying content
      1. :text – String containing markup
      2. :partial – Relative path to a partial
      3. :template – Relative path to a template
  2. Managing Customizations
    1. Application Specific
    2. Extension
    3. Theme
    4. http://guides.spreecommerce.com/extensions.html
  3. Customization Options
    1. View Customizations
      1. Using Deface for view customization
        1. Available actions
        2. Supplying content
        3. Targeting elements
          1. As Spree views are changed over coming versions, the original html elements maybe edited or be removed. We will endeavour to ensure that data-hook / id combination will remain consistent within any single view file (where possible), thus making your overrides more robust and upgrade proof.
        4. Targeting ruby blocks
          1. :replace => "code[erb-loud]:contains('t(:products)')" :insert_before => "code[erb-silent]:contains('elsif')"
        5. View upgrade protection
          1. To ensure upgrading between versions of Spree is as painless as possible, Deface supports an :original option that can contain a string of the original content that’s being replaced. When Deface is applying the override it will ensure that the current source matches the value supplied and will output to the Rails application log if they are different.
        6. Organizing Overrides
          1. The suggested method for organizing your overrides is to create a separate file for each override inside the app/overrides directory, naming each file the same as the :name specified within
      2. Template Replacements
        1. To override any of Spree’s default views including those for the admin interface, simply create a file with the same filename in your app/views directory.
    2. Asset Customizations
      1. Spree’s Asset Pipeline
        1. app |-- assets |-- images | |-- store | |-- admin |-- javascripts | |-- store | | |-- all.js | |-- admin | |-- all.js |-- stylesheets | |-- store | | |-- all.css | |-- admin | |-- all.css
        2. app |-- assets |-- javascripts | |-- store | | |-- spree_core.js | |-- admin | |-- spree_core.js |-- stylesheets | |-- store | | |-- spree_core.css | |-- admin | |-- spree_core.css
      2. Managing your application’s assets
        1. All of your application’s assets should be stored in the appropriate app/assets, lib/assets or vendor/assets sub-directory. All javascript and stylesheet files in app/assets sub-directories will be automatically included by the relevant all.
      3. Managing your extension’s assets
        1. 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
      4. Overriding Spree’s core assets
        1. Overriding individual css styles
          1. Create foo.css after all.css in the same folder. 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.
        2. Overriding entire css files
          1. 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.
        3. Overriding individual javascript functions
          1. Create the same method after all.js at the same folder. The resulting store/all.js would include both methods, with the later being one executed on request.
        4. Overriding entire javascript files
          1. To replace an entire javascript file 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/javascripts directory
        5. Overriding images
          1. 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.
    3. Logic Customizations
      1. Extending Classes
        1. Standard practice for including such changes in your application or extension is to create a file within the relevant app/models or app/controllers directory with the original class name with _decorator appended.
          1. To activate your decorators you need to include the follow code in your lib/spree_site.rb or lib/extension_name.rb file: Dir.glob(File.join(File.dirname(__FILE__), "../app/**/*_decorator*.rb")) do |c| Rails.configuration.cache_classes ? require(c) : load(c) end
          2. Adding a custom method to the Product model: app/models/product_decorator.rb Spree::Product.class_eval do def some_method ... end end
          3. Adding a custom action to the ProductsController: app/controllers/products_controller_decorator.rb Spree::ProductsController.class_eval do def some_action ... end end
        2. Accessing Product Data
          1. If you extend the Products controller with a new method, you may very well want to access product data in that method. You can do so by using the :load_data before_filter. :load_data will use params[:id] to lookup the product by its permalink.
      2. Overriding Controller Action Responses
        1. respond_override method
          1. The respond_override method is used to customize the response from any action, and is built on top of Rails 3’s respond_with method (that all Spree controllers are now using). It accepts a hash of options using the following syntax: respond_override :action_name => { :format => { :result => lambda { ... response ... } } }
          2. :action_name – Can be any existing action within a controller (i.e. :update, :create, :new), provided that action is using respond_with to define it’s response.
          3. :format – The format of the request, (i.e. :html, :json, :js, etc). All Spree controllers have a class level respond_to method call that defines which formats the controller’s actions will respond to.
          4. :result – Two possible results are available on any given response, :success or :failure. :success being the default for most actions, however actions that change or create models will have a :failure response if validation fails for the model being updated.
          5. lambda – The lambda passed contains the actual code to create the desired custom response (i.e. render or redirect_to). A lambda must be passed to ensure the code is evaluated at the correct time.
        2. Example Usage
          1. If you wanted to render a custom partial for the index action of ProductsController, you could include the following in your app/controllers/products_controller_decorator.rb file. Spree::ProductsController.class_eval do respond_override :index => { :html => { :success => lambda { render :partial => "shared/some_file" } } } end Or if you wanted to redirect on the failure to create in Admin::ProductsController, you would use: Spree::Admin::ProductsController.class_eval do   respond_override :create => { :html => { :failure => lambda { redirect_to some_url } } } end
        3. Caveats
          1. If an action does not use respond_with to define it’s response the respond_override will not work.
          2. Some actions contain several respond_with calls so any respond_override defined on it will be executed for any of the respond_with instances, so it’s important to check the model state / logic within the lambda passed to prevent overriding all possible responses with the same override.
      3. Product Images
        1. Spree uses Thoughtbot’s paperclip gem to manage images for products. All the normal paperclip options are available on the Image class. If you want to modify the default spree product and thumbnail image sizes, simply create an image_decorator.rb file in your app model directory, and override the attachment sizes: Spree::Image.class_eval do attachment_definitions[:attachment][:styles] = { :mini => '48x48>', # thumbs under image :small => '100x100>', # images on category view :product => '240x240>', # full product image :large => '600x600>' # light box image } end
        2. Image resizing option syntax
          1. trailing #, image will be centrally cropped, ensuring the requested dimensions.
          2. trailing >, image will only be modified if it is currently larger than the requested dimensions. (i.e. the :small thumb for a 100×100 original image will be unchanged)