Understanding the Shopp Theme API

From 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.

Recommended Reading #

Here are some resources for further reading:

• How the Theme API Really Works – Part 1: The Working Object Context
• How the Theme API Really Works – Part 2: Product Collections
• Creating Your Own Theme API Tags
• Shopp Theme Template Page Hierarchy