The final installment highlights a few of the handy tricks that make the Shopp Theme API a second-to-none tool for templating e-commerce.

How The Theme API Really Works – Part 4: Tricks for Shopp Pros

How The Theme API Really Works – Part 4: Tricks for Shopp Pros

Tricks for Shopp Pros

This series has covered a lot ground with the conceptual underpinnings of the Theme API along with real-world examples to see them in practice. After you get used to how things work, you’ll soon be able to wield Shopp’s API like a well honed swordsman (even dual-wield with the Developer API).

There are a few ninja tricks to the Theme API that will take your templating to masterful levels.

Echo Versus Return

Programmers will be used to the concepts of return values and print or echo statements . Without getting sucked into the pit of hardcore development, it is valuable to know the difference of these two programming mechanisms and how they relate to Shopp’s Theme API.

In PHP the echo or print statement simply outputs a value given to it. The value could be a string (represented in code as a sequence of characters inside either single-quotes or double-quotes: “This is a string.”) or variable that contains a value. When using the term “output”, in the case of WordPress PHP code, we’re talking about sending the string to the browser or printing it out (to the HTML, for example).

The other PHP statement, return, returns program control back to the calling module with (or without) a value. Generally, this means a return value from a function is captured into a variable (not sent to the browser).

That’s the big distinction.

The shopp() Theme API calls are all designed to echo by default. There are some special cases where shopp() calls are designed to determine the truthiness of something like shopp('cart.has-discounts') where it will return a true or false boolean value for use in if statements. Other than those cases though, shopp() “tags” will generally always send output to the browser in the form of the information you requested, or information inside of markup.

What about capturing information from a shopp() tag so you can do more with it? So glad you asked. Shopp has some nifty ways to override this behavior.

You can have the Shopp Theme API return the information rather than echo it by adding a return or echo option to the tag. Both return and echo are known as Universal Options available to all Theme API calls.

$categories = shopp('product.categories', 'return=on');

In the example above, we’re using the product.categories tag to return a list of category names into a variable named $categories. Now we can do some serious templating work by adding in some PHP code into the mix.

For example, you might want to show something specific for a product in the Books category.

$categories = shopp('product.categories', 'return=on');
$categories = explode(',', $categories); // Break up the list into an array
if ( in_array('Books', $categories) ) {
    // Do something exceeding clever
    echo "It's a book!";

That isn’t the most useful example since you could do the same thing with the built-in shopp('') Theme API tag. Still, it illustrates how you can take data as a return value, capture it in a variable and do some extra programming with it before you send it to the browser in it’s final form.

On/Off values

Something else the prior example shows is the use of an on/off option value. All shopp() Theme API tags use the same set of on/off values. When you want to change an option on a shopp() tag to on or off you can use any of the following values

On Off
on off
yes no
true false
1 0

So return=yes works just like echo=off, or return=1 and echo=0. You can use the value set that is most comfortable to you. As a best practice recommendation, what ever value set you choose, stick with it throughout your code.

The Getter Prefix

If you want to skip all that complexity, there is a special way of getting a value returned (AKA suppressing the output and getting the data in a variable). It’s called the get-prefix and is probably the best method to use for returning shopp() Theme API values.

To use it, just add get- to the beginning of a Shopp Theme API property name:

$id = shopp('product.get-id');
$name = shopp('product.get-name');
$slug = shopp('product.get-slug');

As shown in the above example, in dot-notation, you simply add get- after the dot and before the name of the property. It’s that easy, it’s readable, and it’s shorter to type than echo=off or even echo=0 or return=1. The Shopp developers are all about saving programmers from repetitive stress disorder. They have enough of that just being a coder.

Your Own Theme API

There’s even more to explore in the Theme API. Every shopp() Theme API call is routed through several layers of filter hooks. If your eyes didn’t open wide from that, they should have. The implications for that are huge. It means because of the way the Theme API is designed, you can customize the output of every Theme API call in Shopp with your own behaviors. If that’s not enough, because of this design, it means you can even invent your own Theme API tags. Your own tags are added to Shopp like they’ve always been part of it so you can use them in your template code.

For that, you’ll want to jump over to the full article, “Creating Your Own Theme API Tags“.


The Shopp Theme API is an extremely well engineered system refined for flexibly getting information out of Shopp and into re-usable template markup. It provides a convergence point for PHP, HTML, CSS, JavaScript and Shopp technologies with a clearly defined, consistent framework that can be remixed into amazing shopping experiences well beyond what the out-of-the-zip templates can do.


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.