Tutorial: WP e-Commerce Plugin, Theme Customization

This article covers some basic concepts, tips and tricks to help you customize your own WP e-Commerce theme. By the end of this tutorial you will be able to incoroprate WPEC’s elements to your current theme’s layout and design.

Introduction & Concept

WPEC’s theming structure separates each important element of the cart templates into separate files. This way, theme developers can easily manipulate the shopping cart and related pages to match the look and style of their current theme. Given this structure it is possible to create almost any type of design or function you want, the only limit is your imagination!

Each of these various templates, by default, are stored within the WPEC plugin folder. This is where WPEC will look when generating each element on your e-commerce section of your site. However, if you’re wanting to change the look and feel of store you’ll need to move these files to your theme directory, this way they won’t get over-written when you upgrade to later versions of WPEC.

The plugin makes this easy, go to the Settings » Store » Presentation tab and on the right hand side of the page you will see a list of template files with checkboxes next to them. By default none of the checkboxes are checked – this means all the files are still sitting in the plugins folder and that WPEC is still using the default template. But for you to change that, simply select the element you want to edit and click on ‘Move Template Files’. After this is done, the template file you chose will automatically be copied to your current active WordPress theme’s folder. From this point, that’s the copy of the WPEC template you will be working with.

Do this for each template file you want to modify (you may wish to tick all template files). After this is done, it is good practice to click on the button that says ‘Flush Theme Cache’ so that WPEC will know where to look for the template files once they have been moved.

Let’s now see what each of the template files are.

  • compatibility.css – This CSS file is for overriding default styles of a theme. For example in the default WordPress 2010 theme, there are styles for list bullets in the sidebar widgets which will not look good in the WPEC shopping cart widget so there are rules in this file that overrides that styling to no bullets. We will discuss a bit more on this and CSS for WPEC in general later on.
  • wpsc-cart_widget.php – This file is responsible for generating the shopping cart widget you see in the sidebar.
  • wpsc-category_list.php – This file is responsible for generating the category list view when this option is enabled.
  • wpsc-category_widget.php – This file is responsible for generating the category widget in your sidebar.
  • wpsc-default.css – This file is the core CSS file for WPEC plugin.
  • wpsc-featured_product – This file is responsible for generating the featured product display.
  • wpsc-grid_view.php – This file is responsible for generating the product’s grid view display. Please note that this option is only available with the Gold Cart Plugin Upgrade.
  • wpsc-list_view.php – This file is responsible for generating the product’s list view display. This view by default has no product description or image.
  • wpsc-products_page.php – This file is responsible for generating the product’s default view display.
  • wpsc-shopping_cart_page.php – This file is responsible for generating the checkout page display.
  • wpsc-single_product.php – This file is responsible for generating the product’s single detailed page display.
  • wpsc-transaction_results.php – This file is responsible for generating the purchase results after a purchase has been made. For example, the thank you page/message.
  • wpsc-user-log.php – This file is responsible for generating the ‘Your Account’ page where customers can view their previous account purchase history.

As mentioned earlier, you may choose to manipulate only some, or all of these files.

Working with Theme Files in Practice

In this section I will show you how we can manipulate these template files to fit the structure of our current WordPress theme and while I will not be covering every single template file listed, I will show you enough to get your feet wet so you can apply the same technique to other template files.

*Note: I highly suggest using Firefox with Firebug extension so you can easily inspect elements on the fly and quickly see the code responsible for various elements of the layout. I will be using this method throughout this tutorial.

In this example I’m using a plain WordPress theme (one that was not made for WPEC) and will manipulate the template files and CSS to fit the style and look of that theme. I have randomly chosen a theme called ‘Liquorice’ which you can download here

» http://wordpress.org/extend/themes/download/liquorice.2.1.zip.

From this point on I will assume you have your WPEC all setup with demo products and category … etc. If not please do so before continuing so you can follow along with me.

Default Products-Page View

Ok now click on “products-page”. You will see the following screen.

Looking at this screenshot you can see that the product title on top of the product image is sitting too close to the image and could use a bit more breathing room and the “add to cart” button could use some love. We can at this point either open up wpsc-default.css or even the style.css within the theme folder. First you want to go to your Settings » Store » Presentation tab and tick the checkmark on “wpsc-default.css”. Then click on “Move Template Files” so it can be safely moved to your active theme folder where you will be making the edits (don’t forget to also click on flush theme cache after you moved it for safe measures). After that, let’s open up the wpsc-default.css.

In here, find “.default_product_display” CSS rule (Because this is the view we’re working with). Then determine the html element you want to work with – in this case it is the a tag within the h2 tag. So you can form a new rule like so [php].default_product_display h2.prodtitle a {margin-bottom:20px;display:block;}"[/php] It is looking better already. Now there is sufficient space below the product title.

Next let’s make the border around the image to the same color as the borders in the theme so that it gives a more coherent feel. If you look to the right where the sidebar is, go ahead and lift that color off. I used the Firefox color lifter add-on. The color for that is #D1BFA6. Using the firebug element inspector, inspect the product image. If done correctly, you should see that the CSS rule declared for the image border is on line 37 of wpsc-default.css file. Go ahead and navigate to that section and change the border color to #D1BFA6. In addition, lets also make the border width 5px so that it better fits the style of the rest of the theme. Now let’s push the product description away from the product image so it has a bit more breathing room. Using the same technique previously described, inspect the product image element and find the containing parent. In this case it is “.default_product_display .imagecol” on line 98. Add a rule that says “margin-right:20px;”. This will push the description over by 20 pixels thus giving more room in between.

Your products page should now look like this:

Finally let’s see if we can make the “add to cart” button a bit more appealing. As previously, inspect the button and see what CSS line it gives you. You will notice it does not contain a specific style for this button. This is ok because we can always add our own. If you look at the sidebar of the theme and see the search button is blue. We will mimic this color for our “add to cart” button. First sample off that search button’s color. In this case it is #0097A5. Since there are no specific style for this yet, we will use the button’s parent container to drive the specificity. Open up wpsc-default.css and below the rule on line 326, add in

[php].default_product_display .wpsc_buy_button_container input[type=submit] {background-color:#0097A5;outline:none;border:none;cursor:pointer;padding:4px 8px;color:#fff;border-radius:10px;}[/php]. Now you should have a similar button as search button in the sidebar. But let’s take it one step further and add in a hover effect. Below the rule you just added, enter [php].default_product_display .wpsc_buy_button_container input[type=submit]:hover {background-color:#CC4D22;}[/php]. Excellent!! Now your “add to cart” button better suits the rest of the site. If you have followed these instructions closely, you should have something like this:

Single Product Details Display

This page displays the detailed product view of your products. It usually holds all the information of your products along with multiple product images (if you have Gold Cart Plugin) along with full product descriptions and additional information.

To get to this page, click on the title of the product. You should now see this screen:

Hey what gives!! I thought I styled the image borders and buttons!! Not to worry, you can apply the same techniques in the previous section here the same way. The reason why it is no longer styled here is because each view has their own parent containers where default products-page has [php]default_product_display</code> and detailed product view has <code>single_product_display[/php] This is so you can style each section differently if you so choose.

Lets perform the same changes we made in the products-page to our single products view (detailed view). For the image border, it is on line 452. Change the border width and color to [php]border:5px solid #D1BFA6;[/php] After that change, it should look identical to the previous products-page. For the “add to cart” button, there is already a rule that sits on line 481. So lets go to that line in the CSS and add in our own styles. Change the entire rule to [php].single_product_display form.product_form input, #content .single_product_display form.product_form input {padding:4px 8px;margin:0;outline:none;border:none;background-color:#0097A5;cursor:pointer;border-radius:10px;color:#fff;line-height:1.2em;font-size:14px;}[/php] This should give us the same color button as the search. To finish off, lets add the hover effect by adding a rule below that [php].single_product_display form.product_form input:hover, #content .single_product_display form.product_form input:hover {background-color:#CC4D22;}[/php]. You should now have something like this:

Check Out Page

We now move on to the checkout page. Go ahead and add an item to your cart and proceed to the checkout page. It should look something like this:

As you can see by default it does not look too appealing. Lets manipulate the CSS here to make it more presentable using the same technique we used in previous sections.

First we will put some divider lines in the table where it shows the product in the cart. Open up wpsc-default.css on line 850 where it says #checkout_page_container table.checkout_cart tr td, #content #checkout_page_container table.checkout_cart tr td" add in "border:1px solid #ccc;. This will add the border to the cells however you will see gaps inbetween the cells and this is not want we want. We need the cells to collapse without any spacing. To do so, go to line 950 where it says #checkout_page_container table.checkout_cart and add in the rule border-collapse:collapse;. Refresh and you should see your newly adding border styling in action.

Next we will space out the form fields to make them look better. This rule does not exist in the CSS so lets add this in ourselves. In wpsc-default.css add [php].wpsc_checkout_table td {padding:5px;}[/php]. Then lets give it a background color and full width by adding [php].wpsc_checkout_table.table-1 {background-color:#D1BFA6;width:100%;margin-bottom:20px;box-shadow:inset 0 0 3px rgba(0,0,0,0.4);padding:5px;}[/php] Ahhh… now it is looking great! That was the billing section, now move on to the shipping section.

For the shipping section, lets make the background color slightly different from the billing so that it is immediately distinguishable. Add in [php].wpsc_checkout_table.table-2 {background-color:#dfb781;width:100%;margin-bottom:20px;box-shadow:inset 0 0 3px rgba(0,0,0,0.4);padding:5px;}[/php]. It is now starting to take shape.

You should have something like this:

But what about that hideous default purchase button!! I am glad you asked…We will change that now!

For the button add in the following rule

[php]#checkout_page_container input.make_purchase {font-size:14px;background-color:#CC4D22;outline:none;border:none;cursor:pointer;color:#fff;padding:4px;border-radius:5px;border:1px dashed #fff;}". And for the hover add "#checkout_page_container input.make_purchase:hover {color:#000;}[/php]

Finally, lets make the total amount text on the bottom a bit bigger by adding [php].wpsc_checkout_table.table-4 {font-size:20px;}[/php]. And there you have it, your checkout page has now come to life and closely matching with the theme.

Utilizing the techniques and knowledge you’ve learned from the previous exercise, you can apply it to all template files the same way. You should be able to manipulate the template’s CSS to your heart’s content.

Tips & Tricks

  • You can unload the default styles of WPEC and run your own styles in your theme CSS by putting this in the functions.php wp_deregister_style('wpsc-theme-css');. Of course you should wrap that around with a function and call it in a WordPress action like add_action( 'wp_print_styles', 'my_deregister_styles', 100 ). This way you save on 1 http request and you can consolidate all the WPEC styles into 1 main CSS stylesheet.
  • Only move the template files that you’re going to alter. Leave the rest unticked in the presentation tab.
  • The CSS rules with “#content” was originally there because of the default WordPress theme TwentyTen. The purpose of to override the specificity so WPEC could be styled properly. However if you’re using a custom theme, most likely that is not used anymore therefore you can ignore using that rule when you apply custom rules.
  • If you’re using grid view on your products-page, take note that the CSS style is inside the Gold Cart Plugins folder. So any changes to the style has to be made there or you can override it in your main theme’s CSS. You can also opt to disable/remove this CSS to be consolidated into your main theme’s CSS like previously mentioned.
  • There is a dynamic width calculation for the grid view within Gold Cart that may not work for your theme rendering your layout to be semi broken. To disable this, open up gold_cart.js inside the Gold Cart’s js folder and comment out line 154.


WPEC is an extremely versatile e-commerce plugin when it comes to theme development – more so than all the competitors I’ve seen to date. Almost every aspect of the template/cart can be manipulated to your imagination. But don’t take my word for it – please have a look at the following sites that were develop on WPEC.

You can see these wonderful themes firsthand at http://splashingpixels.com