Customizing Templates and Template Parts

This document explains the template hierarchy provided by the new theme engine, along with a list of templates and template parts that you can use.

You’re recommended to practice the “exercises” to get a hang of the template system.

Customizing templates

Template hierarchy

The process that theme engine v2 uses to determine which template to load is illustrated in the diagram below.

Template Hierarchy

For example, if you go to http://yoursite.com/store/, the theme engine will do the following:

  1. Resolve the slug ‘store’ and matches it with the main store page.
  2. Because the main store page is essentially a list of posts with wpsc-product post type, the theme engine will look for archive-wpsc-product.php template within your theme’s folder.
  3. If archive-wpsc-product.php is missing, it will continue to search for main-store-wrapper.php template from the subfolder wp-e-commerce of your theme.
  4. If main-store-wrapper.php is missing, the theme engine will eventually fall back to page.php.

So you can use the diagram above to determine the file structure of the templates you want to customize. Just follow these 3 steps:

  1. If it’s the main store (product archive), product category page (taxonomy archive) or single product, create a post type / taxonomy / single post type template that follows the naming convention of WP core template hierarchy (archive-wpsc-product.phptaxonomy-wpsc_product_category.php, or single-wpsc-product.php respectively).
  2. Otherwise, create a subfolder within your theme and name it wp-e-commerce. This is where you will store your templates and template parts.
  3. Create the template inside the wp-e-commerce subfolder.

Try it out

This little exercise will help you get the hang of the template hierarchy.

  1. On your test site, switch the theme to Twenty Twelve.
  2. Create a couple of test products.
  3. Open the store page (e.g. http://yoursite/store). Confirm that you’re seeing a list of products.
  4. Create a subfolder inside your theme and name it “wp-e-commerce”.
  5. Create a template inside the subfolder wp-e-commerce and name the file main-store-wrapper.php. Write “Hello World” as the content of that file.
  6. Reload your store page. You should see “Hello World”.
  7. Create a template inside your theme folder (but outside of wp-e-commerce subfolder), and name it archive-wpsc-product.php. Write “Hello from Product Archive Template.”.
  8. Reload your store page. You should see “Hello from Product Archive Template.”
  9. Try customizing other templates.

Loading the default template part

Inside page.php, normally the_title() and the_content() will output the post title and content of a page. However, in case of a WP e-Commerce template, if page.php is used, some magic happens. the_title() will properly output the WPEC-related page’s title, while the_content() will automatically locate and load the proper template part within the page.

However, if a custom template is found and page.php is not used, the template part will need to be loaded manually from within the custom template, by calling wpsc_get_template_part() with no arguments. The function wpsc_get_template_part() works as follows:

  1. If no arguments are passed, it will assume you want to load the template part corresponding to the WPEC-related page being displayed. Otherwise it accept similar arguments as load_template_part().
  2. wpsc_get_template_part() will first look for the requested template part in this particular path: wp-content/themes/your-theme/wp-e-commerce/template-parts.
  3. If the requested template isn’t found there, it will load the default template part found in wp-content/plugins/wp-e-commerce-theme-engine-v2/mvc/views.

Try it out

This example continues the template hierarchy exercise above. Make sure you have the archive-wpsc-product.php template in place for this.

  1. Make sure you’re using Twenty Twelve theme and already created archive-wpsc-product.php as instructed in the first exercise.
  2. Open the archive-wpsc-product.php template inside your theme folder.
  3. Replace the content of that template with the following lines:
<?php get_header(); ?>
    <div id="primary" class="site-content">
        <div id="content" role="main">
            <header class="entry-header">
                <h1 class="entry-title">My Awesome Store</h1>
            </header>
        </div><!-- #content -->
    </div><!-- #primary -->
<?php get_sidebar(); ?>
<?php get_footer(); ?>
  1. Open the store page (http://yoursite/store) and you’ll see a basic layout with header, sidebar, footer and a custom title My Awesome Store, but you don’t see any store contents.
  2. Load the default template part for the store page by adding this line below the </header> line and before the <div><!-- #content --> line:
<?php wpsc_get_template_part(); ?>
  1. Go back to your browser and refresh the store page. You will see the products there. The template part being used for the product list is located in /wp-content/plugins/wp-e-commerce-theme-engine-v2/mvc/views/main-store.php.

Customizing Template Parts

Now that you know how to use a custom template, you might want to customize the inner template parts as well. This is totally possible and can be done in three steps:

  1. Determine which template part you want to customize. See the “Template Parts In Detail” section.
  2. Copy the default template part that you want to customize from /wp-content/plugins/wp-e-commerce-theme-engine-v2/mvc/views to /wp-content/themes/your-theme/wp-e-commerce/template-parts (this requires manual copying for the time being, but a UI will be added to make it easier).
  3. Modify the template you just copied in your theme’s template-parts folder. Make sure you don’t alter the name of the template part file.

The custom template will now be loaded instead of the default one supplied by the plugin.

Try it out

This example continues the template exercises above.

  1. The template part for the main store page is located at /wp-content/plugins/wp-e-commerce-theme-engine-v2/mvc/views/main-store.php. Copy this file into your theme’s wp-e-commerce/template-parts folder.
  2. Delete the whole content of the file and write “Hello World”, then save.
  3. Refresh the store page and you’ll see that your custom template is being used, but the inner template part has been replaced with “Hello World”.
  4. Delete the main-store.php template part inside your theme and the default template part will be loaded again.

Template Parts in Detail

Main Store

This page only has one template part: main-store.php. Default location: /wp-content/plugins/wp-e-commerce-theme-engine-v2/mvc/views/main-store.php.

Inside main-store.php, it loads another template part called loop-products.php, in which another template part is loaded: product-excerpt.php.

Product Category

This page only has one template part: category.php. Default location: /wp-content/plugins/wp-e-commerce-theme-engine-v2/mvc/views/category.php.

The category.php template part also uses loop-products.php.

Single Product

This page only has one template part: single.php. Default location: /wp-content/plugins/wp-e-commerce-theme-engine-v2/mvc/views/single.php.

Shopping Cart

This page only has one template part: cart.php. Default location: /wp-content/plugins/wp-e-commerce-theme-engine-v2/mvc/views/cart.php.

Login

This page only has one template part: login.php. Default location: /wp-content/plugins/wp-e-commerce-theme-engine-v2/mvc/views/login.php.

Register

This page only has one template part: register.php. Default location: /wp-content/plugins/wp-e-commerce-theme-engine-v2/mvc/views/register.php.

Password Reminder

This page has two template parts, depending on the scenario:

  • password-reminder.php is used when the user is requesting password retrieval instructions via email.
  • password-reminder-reset.php is used when the user is resetting their password.

Checkout

This page has 6 template parts, depending on the scenario:

  • checkout-login-prompt.php Loaded when the customer is not logged-in. They will be prompted to either login, or checkout as a guest customer.
  • checkout-login-required.php Loaded when the customer is not logged-in, and a customer account is required for checking out (as specified in Settings->Store->Checkout).
  • checkout-shipping-and-billing.php Loaded when the customer is at the first step of the checkout process: Shipping and Billing details.
  • checkout-shipping-method.php Loaded when the customer is at the second step of the checkout process: Shipping Method
  • checkout-payment.php Loaded when the customer is at the third step of the checkout process: Payment Method
  • checkout-results.php Loaded when the customer has completed the purchase and is shown the transaction results.

Customer Account

This page has 4 template parts, depending on the scenario:

  • customer-account-index.php This is the main listing of customer purchase history.
  • customer-account-order.php Loaded when the customer is viewing a particular order’s details.
  • customer-account-digital-content.php Loaded when the customer is viewing the “Digital Contents” they have purchased.
  • customer-account-settings.php Loaded when the customer is viewing the “Settings” tab.