Unlock the secrets of the Shopp Theme API starting with part 1 of a series that will teach you everything, taking you from beginner to master.

How the Theme API Really Works – Part 1: The Working Object Context

77384_6821

How the Theme API Really Works – Part 1: The Working Object Context

Shopp is so flexible and easy to develop with in part because of it’s well defined and consistent APIs. When you’re new to developing with Shopp though, things can seem a bit out of place from what you’re used to in WordPress development.

How WordPress Does It

In WordPress, you’re probably used to The Loop and WP_Query. Shopp, at first glance doesn’t appear to have any of that. Au contraire! Shopp does have constructs that are very similar but with a different approach to both.

<?php 
    if ( have_posts() ) {
        while ( have_posts() ) {
            the_post(); 
        } // end while
    } // end if
?>

When using The Loop in WordPress you are either relying on the query that WordPress already ran when the page request was being processed, or you are running your own query using WP_Query.

How Shopp Does It

Shopp follows a really similar strategy. Take a product page as an example. Shopp jumps in during request processing and determines when a product page has been requested. Shopp takes the custom post type that the WP_Query loaded and converts it into a ShoppProduct runtime object that Shopp can use.

Now back to WordPress. In order for post “tags” like the_title() or the_content() to work, WordPress has to set a post to work from. This happens using have_posts() to work through the list of loaded posts, and then using the_post() to set a current “working” post container using a global variable.

Shopp does the same thing. Instead of using have_posts() to go through a list, on the product page Shopp uses the Theme API tag shopp('product.found') to set the “found” product for other shopp('product...') tags. Back to this in a moment, but first, let’s cover how to call Theme API tags.

The shopp() Gateway Function

Theme API tags all use one function: shopp(). Inside of the function parameter list (inside the parentheses) you give it a string that indicates the object (the context) you want to work with, and the information you want to display in your template. The form and notation used in shopp() tags can vary, so for now we’ll explain the simplest method using “dot-notation”.

When you use a shopp() tag you always need to specify an object (also known as the “context”) and the information you want. For example, to display the current total for the shopping cart you would use:

<?php shopp('cart.total'); ?>

That tag would display something like:

$1,125.00

In the example we’re using dot-notation because the object name (cart) is separated from the information we want displayed (total) by a dot (.). You can only use supported object contexts and their information tags, you can’t go around making up stuff you want to display. Well, you can, but that’s covered in another article. In most cases you’ll want to use the Theme API Reference to lookup what object contexts and information tags are available to use.

A second parameter can be added to any shopp() tag to provide special options that can change the way the requested information is displayed. For example, if I want to show the current shopping cart total, but without any of the currency formatting I can turn the money option off.

<?php shopp('cart.total', 'money=off'); ?>

Using our same wildly optimistic order total from before, this code would show:

1125.00

To separate the parameters given to shopp() you use a comma (,). Notice that both parameters, the tag name and the options, are wrapped in single-quotes ('). You can use either single-quotes or double-quotes, but you need to use either of them to wrap the parameters so that PHP will interpret them as separate strings.

The Working Object Context

Now back to where we left off with setting up the products for use. When the_post() is run, WordPress is really just setting a global container that the other post functions the_title() and the_content() will pull information from. In other words WordPress sets the working post “context” that the_title() will use.

For Shopp products on a product page shopp('product.found') does the same job. It sets up the working context as the requested ShoppProduct object so that the entire compliment of shopp('product...') tags like shopp('product.name') and shopp('product.url') will work as expected displaying the name of the product and the permalink URL of the product.

<?php
if ( shopp('product.found') ) {
    shopp('product.name');
    shopp('product.url');
}
?>

If you tried to call shopp('product.found') from outside of a product page template, say on a WordPress post in the single.php template file, you would be sorely disappointed. Since the query for a post page will load a WordPress post, not a Shopp product, shopp('product.found') will fail and no product will be set as the working context. That means shopp('product...') tags will not work. None of them.

That brings up a good question. What if you need to load a product on your own, like WP_Query? No problem, you can use the shopp('storefront.product') tag to retrieve a product for use by shopp('product...') tags.

shopp('storefront.product', 'slug=awesomesauce');

This tag will retrieve a product on command, but by default it will also display the product using the product.php content template file from your Shopp templates. Handy as that is, that’s not exactly what we want if we’re trying to do something custom. To turn it off we need to add a second option to our options list. In this case we want to add a load option to tell Shopp to load the product, not display it.

shopp('storefront.product', 'slug=awesomesauce&load=true');
shopp('product.name');

To add more than one option to the options list, you use a ampersand (&) to join them together inside the quotes. Adding load=true to the option list for the storefront.product tag will load the specified product so it will be used for other shopp('product...') tags. The code above will display the name of the product, in this case: Awesomesauce.

Using the storefront.product tag, you can change the working product at any time. This is what Shopp means when we talk about an object context. Without loading a product either by a page request, or by using programming to load a specific product object, none of the shopp('product...') tags will work. To change the product that the shopp('product.name') uses to display a product name, just change the product context again.

// Load Awesomesauce
shopp('storefront.product', 'slug=awesomesauce&load=true');
// Display the product name: Awesomesauce
shopp('product.name');

// Load Amaze-balls
shopp('storefront.product', 'slug=amaze-balls&load=true');
// Display the product name: Amaze-balls
shopp('product.name');

Nothing goes better with Awesomesauce than Amaze-balls. Here’s the important part. The code above is key to understanding how the working object context changes. In this case we’re only working with the working product context to keep things simpler.

In the sequence of code above, you see the current product context is setup to use the Awesomesauce product. After the loading statement shopp('storefront.product') the product loaded into the working context is Awesomesauce and all shopp('product') tags will show information from Awesomesauce. It will continue to do so until something comes along to change the context. In the code above, that happens when shopp('storefront.product') is run again to load Amaze-balls. After that, the shopp('product') tags will only show information from the Amaze-balls product until the context changes by some other Theme API tag or the page display is finished.

In this case, the shopp('storefront') tags are being used to manipulate different object contexts. There are lots of other tags that can change the working context and for different context types of which there are several. You’ll be introduced to more context types in the rest of this series.

Knowing Is Half The Battle

Now you have a good understanding of the difference between how products are loaded by Shopp automatically during a page request, and how you can load products on demand using the Theme API. You also got a taste of the basic structure of shopp() tags using the dot-notation to call a specific tag: shopp('context.information', 'options...'). Understanding how the options list works using the ampersand to join options opens up a new world of possibilities and will give you the flexibility you need to change how things look in a template file.

Using Theme API tags requires understanding what the working object context is so you know when to use the right set of tags. This gives you a good beginning understanding to build upon.

Look for part 2 of this series where we explore loading entire categories of products using the Theme API.

Avatar of Jonathan Davis

By

Jonathan was born at an early age and began designing and developing shortly after. He is the founder of Ingenesis Limited and Project Lead on the Shopp e-commerce plugin for WordPress. He lives and works in the heart of the midwest US with his family. He fancies himself a designer of code, and is only slightly addicted to coffee.

You must be logged in to post a comment.

© Ingenesis Limited. Shopp™ is a registered trademark of Ingenesis Limited.

Skip to toolbar