Clif Griffin | Contributing Author, Sell with WPFrom the Editor: This is a guest post from Clif Griffin, who is a WordPress developer, consultant, and Shopp core contributor. You can find more information about Clif’s work at CGD, Inc.

Some readers have emailed to request help on how to theme eCommerce plugins, and this post will help those of you with at least beginner-to-intermediate skills in theming WordPress. Thanks Clif!

One of the most important aspects of any WordPress eCommerce system is theming.  When tasked with matching a catalog page to a design, you can easily lose a lot of time if your eCommerce themes are full of programming logic, or have awkward, difficult to remember syntax.

Shopp takes a very lean approach to theming that I think makes it very easy to manipulate.  However, it’s non-standard syntax can be a little bit intimidating at first.  This article will take you step-by-step through the theme API and expose not only its usage, but a little bit of its inner workings.

Getting Started #

The Shopp Theme API hinges around a single function:

shopp();

This function takes three separate arguments:

$object

This specifies the object context of the data you are accessing.   Sounds complicated, right? It isn’t really, the valid values of this look like: product, category, cart, checkout, customer, purchase, storefront, etc.

Quite simple really!  I use the term “object context” because I think this helps expose the underlying functionality: the value provided here simply tells Shopp which object it is retrieving data from, rather than making you remember the various ways of directly accessing these objects. (Because this is a theme, not a plugin!)

$information

The information tag is simply the attribute you’re requesting.  This could be a bit of information such as the title of a product, but it could also be a boolean question such as ‘has products’ for use in loops.  I’ll show an example of both of these things soon.

$options

Options are optional, and allow you to make changes to the way the requested data will be returned or displayed. You can pass these in as an ampersand (&) separated list or an array.

Putting it Together With Some Examples #

At this point you may or may not be questioning my premise that the Shopp Theme API is easy to use, but bear with me.  I’ll give you some examples to help demonstrate how this works in practice.

Example #1: Product Price

Using the above data, you may be able to guess the way you would show a product’s price:

shopp('product','price');

That was easy.

But what if we wanted to show the price without the currency symbol (i.e., $ for USD)?

shopp('product','price','money=off');

Simple, right? That money option actually works for any monetary value within the Theme API.

Example #2: A Category Loop

For this example, we’ll demonstrate how you would loop through a category and show the products contained therein. For the moment, we’ll assume this is actually on a category page, and that a category is already loaded.

<?php if ( shopp('collection,'has-products') ) :?>
    <div class="products">
    <?php while( shopp('collection','products') ) : ?>
        <div class="product">
            <a href="<?php shopp('product','url'); ?>">
                <?php shopp('product','coverimage','width=200'); ?>
            </a>
            <h3><?php shopp('product','name'); ?></h3>
            <h4><?php shopp('product','price'); ?></h4>
            <?php shopp('product','add-to-cart'); ?>
        </div>
    <?php endwhile; ?>
    </div>
<?php endif; ?>

Hopefully this example is self-explanatory. We first check to make sure the category has products, and then loop through the products, showing the cover image, the name, and the price.

But, what if we are somewhere else and we don’t have a category readily available? You can actually use the Shopp Theme API to load a category, tag, or other collection:

// load books category
shopp('storefront','category','slug=books&load=true');

// load red tag
shopp('storefront','tag','slug=red&load=true');

// load related products collection
shopp('storefront','related-products','load=true');

The “load=true” option in each of these examples tells Shopp to load that category into memory, but not to immediately display it. If you were to omit this option, it would actually display the default category loop right away. So, the load option is usually used when you want to do a custom loop.

If you’re wondering how you would switch back to the original object context, this is easy too:

// switch back to product after category loop (assuming you're on a product page)
shopp('storefront','product',"reset=true");

// switch back to original category after custom loop
shopp('storefront','collection',"reset=true");

Get vs Echo

By default, the Shopp Theme API always echoes the data you are requesting. But, there’s a standard way to tell Shopp to return the data for storing in a variable. Consider this example:

$price = shopp('product,'get-price');

This works with all, tags that access data. You simply drop ‘get-‘ in front of the property and Shopp will return it instead of echo.

A Final Word On Syntax

I hope this has been a helpful primer on the basics of the Shopp Theme API, but I’d like to finish by pointing out that Shopp actually has a pretty loose syntax, that gives you several ways to ask for the same thing depending on your preferences.

Take a look at these examples:

shopp('product','addtocart');

shopp('product','add-to-cart');

shopp('product.addtocart');

All of the above statements are 100% equivalent. In fact, Shopp first strips out the dashes from all input so you can use the dashes as you want, for your own readability preferences. If using the dot syntax (object.information), the second parameter is treated as the options.

Lastly, you can pass options as an array instead of a comma separated list. Example:

shopp('storefront','category','slug=books&show=5&load=true');

$options = array('slug' => 'books', 'show' => 5, 'load' => true);
shopp('storefront','category', $options);

Again, both statements are treated as 100% equivalent.

Any Questions?

That’s it for now! I hope this has helped you build a stronger understanding of the Shopp Theme API. If you have any questions, leave a comment and I’ll do my best to answer them.

Here are some resources for further reading:


Your eCommerce stores loses almost 70% of carts due to abandonment. Did you know that you can typically recover 10-15% of these sales? Try Jilt for free to save these carts – most stores see 10-15% more revenue with their first recovery campaign.


Posted by Clif Griffin

Clif is a WordPress core contributor, consultant, and Shopp plugin core contributor. He builds custom eCommerce solutions and Genesis eCommerce child themes. You can find more information about Clif’s work at CGD, Inc.

3 Comments

  1. Thanks Clif for this informative post!

    I think the Shopp API is very intuitive and easy to use. But information like your post helps connecting the dots and gives a better understanding of the basic principles of the API.

    I’m working on a site where I want parent categories to display like:

    ParentCat1 name
    product1, product2, product3..

    ParentCat2 name
    product1, product2, product3, product4..

    This is the site:
    http://troskodesign.com/shop/category/new-collection/

    Right now I’m using code like this in category.php:

    if(shopp(‘collection’,’hascategories’)):
    while(shopp(‘collection’,’subcategories’)):
    shopp(‘subcategory’,’name’);

    $category_id = shopp(‘subcategory’,’get-id’);
    shopp(‘storefront’,’category’,’id=’.$category_id.’&load=true’);

    product-loop

    shopp(‘storefront’,’collection’,”reset=true”);
    endwhile
    else
    product-loop

    Is there a smarter way where I don’t have to maintain the same product-loop code in two places? Import it from an external file would probably be better but I’d like to hear your thoughts on my usage of the API in this example.

    Thanks!

  2. Hi Ben,

    The mistake you are making is loading the subcategory separately. The correct way is to directly loop through the subcategory. You don’t have to use either of these lines:
    $category_id = shopp(‘subcategory’,’get-id’);
    shopp(‘storefront’,’category’,’id=’.$category_id.’&load=true’);

    Doing so messes up the context for the outer loop, so you’ll never get it to load the next subcategory after each loop.

    So, do something like this:
    if(shopp(‘collection’,’hascategories’)):
    while(shopp(‘collection’,’subcategories’)):
    shopp(‘subcategory’,’name’);

    product-loop

    shopp(‘storefront’,’collection’,”reset=true”);
    endwhile
    else
    product-loop

  3. Hi, I have a problem with AJAX pagination. I decide to get products with AJAX but I have no idea where I should put the page number. For example during simple WP_Query request I just set ‘paged’ option with number I need. But how it works with Shopp?

Comments are closed.