More at Features | Support | Blog | Demo | Community | Download

Tutorial: A Customization Extension

This guide contains a tutorial for the development of an extension to customize the appearance of the standard Spree installation. After reading this guide you should learn:

1 Preliminaries

We assume that you are running Spree from an installed gem, and have created a new project using the spree command. This is the easiest mode to start with. Configure the database(s) as you wish and run the server.

The new project will already have a site extension created by default, located in vendor/extensions/site. It should contain a few skeleton files already. We will create a new theme to hold the changed views templatew

When any files in an extension’s public/* directories are modified, such as CSS or JS files, a server restart is required to copy these files over to the main app public/ directory. Kill and rerun script/server, or if using Apache Passenger, use touch tmp/restart.txt+, etc.

2 Creating a Theme Extension

First, run the following to create a theme extension by the name of ‘my_theme’.

script/generate theme my_theme

This command will create several files in the vendor/extensions/my_theme directory. The contents will look similar to a generic rails application - it’s the subset of files needed in extension, restricted to the files that are useful for view changes.

Now change into this new directory.

3 Add a Custom CSS Stylesheet

New themes contain a copy of the core Spree style file (called screen.css). You can edit this if you wish, or add some new files. This part of the tutorial explains how to add a custom CSS stylesheet to change the look of your site.

3.1 Create the custom stylesheet

Create a file named public/stylesheets/my_theme.css. Edit this + to contain the following: body { background: #99CC99; }

3.2 Add the stylesheet to the default layout

Now you’ll tell Spree to include the custom stylesheet in the default layout by changing the stylesheets preference.

Put this code in an initializer, e.g. in config/initializers/my_theme.rb.

Spree::Config.set(:stylesheets => 'screen,my_theme')

3.3 Results

After the server has restarted, refresh your browser to verify the background colour changes have taken effect.

Custom CSS Part 1

3.4 Another Iteration

Complete the following steps to perform another iteration of style changes:

Apply the following patch on my_theme.css and restart the server.

body { background: #99CC99; } + body.two-col div#wrapper { + background-image: none; + background: #FFF; + -moz-border-radius: 10px; + -webkit-border-radius: 10px; + }

View the results:

Custom CSS Part 2

4 Using Custom Logos

The following describes how to use a custom logo on your site.

4.1 Override the default logo path

Change the default path Spree uses for the logo image file by adding the following line to an initializer (see above).

Spree::Config.set(:logo => '/images/logo.png')

4.2 Upload the image

Next, create a public/images directory with the following command:

mkdir public/images

Then, retrieve this image and save it to your SITE_EXTENSION_DIR/public/images/ directory, then restart.

wget mv logo.png SITE_EXTENSION_DIR/public/images/logo.png

4.3 Results

View the results:

Custom Logo

5 Customizing the Layout

If you need greater layout customization than changing the logo and stylesheets allow, then override the Spree layout template.

To demonstrate we’re just going to add a “Hello World” message to the layout.

5.1 Copy the layout template

We’ll copy the existing layout template to our site extension before we customize it.

First, complete the following command to make a new directory:

mkdir SITE_EXTENSION_DIR/app/views/layouts/

Copy the Spree gem’s spree_application.html.erb layout file to your extension app/views/layouts/ directory.

cp GEM_ROOT/app/views/layouts/spree_application.html.erb SITE_EXTENSION_DIR/app/views/layouts/

5.2 Edit the layout template

Edit the SITE_EXTENSION_DIR/app/views/layouts/spree_application.html.erb file to contain the following HTML between the opening body tag and the first div tag: <h1>Hello World</h1>

5.3 Results

Refresh the site in your browser, and see that there is now a “Hello World” message that wasn’t there before. Now go back and delete <h1>Hello World</h1> from the file you edited in the previous step, you won’t need it for the rest of the tutorial.

6 Using Custom Javascript

This final step of the tutorial describes how to add custom javascript to your site by modifying the head partial template file.

6.1 Copy the head partial

We’ll copy the existing head partial template to our site extension before we customize it.

First, complete the following command to make a new directory:

mkdir SITE_EXTENSION_DIR/app/views/shared/
6.1.1 Spree Application Installation

If you are running Spree as an application, copy the Spree _head.html.erb partial to your extension app/views/shared/ directory.

cp SPREE_ROOT/app/views/shared/_head.html.erb / SITE_EXTENSION_DIR/app/views/shared/
6.1.2 Gem Installation

If you are running Spree as a gem, copy the Spree gem _head.html.erb partial to your extension app/views/shared/ directory.

cp GEM_ROOT/app/views/shared/_head.html.erb / SITE_EXTENSION_DIR/app/views/shared/

6.2 Edit the head partial

Apply the following patch to SITE_EXTENSION_DIR/app/views/shared/_head.html.erb to include site.js on all of your application pages. The rails helper will be used to consolidate and cache the three javascript files into one file to be included on all pages.

- <%= javascript_include_tag 'jquery-1.3.2.min', - 'jquery.validate.min.js' :cache => 'jquery-and-plugins' %> + <%= javascript_include_tag 'jquery-1.3.2.min', + 'jquery.validate.min.js', 'site.js' + :cache => 'jquery-and-site' %>

6.3 Create the Javascript

Spree endorses the use of jQuery rather than the Rails convention of Prototype. Using Prototype will most likely cause jQuery conflicts.

Create a new directory to house the javascript in the SITE_EXTENSION/public/javascripts/ directory.

mkdir public/javascripts/ vi public/javascripts/site.js

Add the following code to site.js and restart:

$(function() { alert('hi'); })

6.4 Results

Refresh your browser to see the new alert message on page load:

Custom Javascript Part 1

6.5 Another Iteration

To complete another iteration of javascript changes, replace site.js with the following code:

var are_you_sure = function() { return confirm('Are you sure you would like to add this item to your cart?'); }; $(function() { $('div#cart-form button').click(function() { return are_you_sure(); }); })

Restart the server again.

Upon adding an item to the cart, you will be prompted with the following message:

Custom Javascript Part 2

7 Notes

7.1 Git

git status

Your new site extension files will be identified as untracked files by git. These should be added to the main repository.

Additionally, the files copied over from the SITE_EXTENSION_DIR/public/ directory will show as untracked files by git as well. These files can be ignored (by modifying +.gitignore) or added to the main repository.

7.2 Deactivation

At this point in time, to deactivate your site extension, move the SITE_EXTENSION_DIR out of the vendor/extensions directory.

mv vendor/extensions/site/ ~/