For the third installement of this series we review the different object contexts available in Shopp.

How the Theme API Really Works – Part 3: More Context

nautilus

How the Theme API Really Works – Part 3: More Context

Our first look at the Theme API in Shopp introduced the working object context. In the Shopp Theme API, context is everything. What do we mean when we talk about context? Primarily it refers to the data that is available when the template code runs, or the data that is loaded before the template code runs.

When browsing pages on the site, different data is loaded by Shopp. When a product page is requested, Shopp loads the requested product automatically. That is what makes the data available for the shopp('product…') tags. On a product page, we have a product context, so that shopp('product…') tags will work.

The same sort of logic applies to product category pages. A product category collection is loaded automatically by Shopp figuring out which category was requested from the URL. It sets up the collection context for shopp('collection…') tags.

There are several different object contexts that Shopp provides. What follows is a brief overview of each object context, when they are available and what templates they are usually found in. The built-in contexts include:

  • Product
  • Collection
  • Cart
  • Cart Item
  • Checkout
  • Customer
  • Purchase
  • Shipping
  • Storefront

Product Context

For a complete look at the product context you’ll want to review the first part of this series, “How the Theme API Really Works – Part 1: The Working Object Context“. A reference to all of the product tags exists on the Shopp API Reference site.

Collection Context

The collection context is covered in part 2 of this series, “How the Theme API Really Works – Part 2: Product Collections“. You can find the collection tag reference on the Shopp API Reference site.

Cart Context

The cart is a special context because it is always loaded and always available. The contents of the cart and the current totals for the order are kept in session data that is tracked via a cookie. That session data gets loaded very early in the page load process because it uses PHP session hooks. If you’re curious about PHP session hooks, you can read more about it, but knowing how they work isn’t required to understand that the cart is available on any page because of session data. It means you can use shopp('cart…') tags in any WordPress theme template file like header.php, sidebar.php, footer.php, or even functions.php. Anywhere you need shopping cart information.

You’ll find cart tags most often in the cart.php, summary.php and sidecart.php Shopp content template files. Check the API Reference for all the available cart tags.

Cart Item Context

Where the cart object is really a container object, a cart item is a loop-context object. That means you generally have to use a loop to set the current cart item context since the cart can have lots of cart items in it.

Depending on if you want to access a specific item in the cart, or show each item in the cart, you will need to set the current cart item context.

if ( shopp( 'cart.has-items' ) )
    while ( shopp( 'cart.items' ) )
        shopp( 'cartitem.name' );

This simple loop structure makes sure there are items in the cart with shopp('cart.has-items') then loops through each of the items in the cart showing the name of each. The entire set of available cartitem tags is on the API Reference site.

Checkout Context

The checkout context is an umbrella for checkout data that, like the cart context, is automatically loaded from session data. The data is loaded early in the process following PHP session hooks and is available in any WordPress theme template file or Shopp content template. The checkout context is primarily responsible for customer information such as the customer name, billing address and shipping address and card payment details as it relates the in-progress order.

Usually you only find shopp('checkout…') tags used on the checkout.php Shopp content template, but in theory it can be used on any theme template or Shopp content template.

See all of the checkout tags on the API Reference site.

Customer Context

The customer context relates to the logged-in customer. The customer context object is shared with the checkout context and so the only distinction is when and how the customer data is being used. When dealing with non-checkout tasks such as account profile management, the customer context is used. During the checkout process, the checkout context is used because the shopp('checkout…') tags are tailored for the checkout experience.

Sharing the data with the checkout context from the session data means the customer context is also available everywhere, in any theme template or content template. Most often, though, you’ll see the shopp('customer…') context tags used in the account.php, account-{slug}.php and login.php Shopp content template files.

The customer context tags are documented on the API Reference site.

Purchase

The purchase context is only automatically made available in a couple of special areas. The first is when an order is loaded during an order lookup such as when a customer is logged into their account and pulling up an order in their order history. The other time it happens automatically is when the in-progress order is submitted. The order becomes a purchase record that is accessible in the purchase context of shopp('purchase…') tags.

The primary template you see purchase tags is in the receipt.php Shopp content template which gets a lot of re-usable mileage. It’s used whenever an order needs rendered: pulling up an order in the order history, on the thanks page when an order is completed and in the order notification emails that are sent out to the merchant and customer.

The API Reference site has a complete guide to the checkout template tags.

Shipping Context

The shipping context is available when there are shipping methods that apply to the in-progress order. This happens in special circumstances: an order must have shipped items in the cart and there must be at least one shipping method that applies to the in-progress order that is based on the destination of the order.

This context allows you to work with and display information related to the available shipping methods for the order including name, cost estimate and delivery timeframe.

All of the shipping tags are documented on the API Reference site.

Storefront Context

The storefront context is an always available controller object for the Shopp storefront experience. It can be used in any WordPress theme template file or Shopp content template.

The storefront tags can be used for loading new contexts like products and collections (especially smart collections), showing search forms, aside widgets, collection view controls, navigation breadcrumbs and more. It’s kind of the utility belt of the Shopp storefront.

See the complete reference of storefront tags on the API Reference site.

Contexts Work Together

You should have come away with the idea that different context tags can be mixed together to remix how Shopp works and loads data. This mix and match of different tags from different contexts in Shopp allows for unique “composability” that enables layouts that would otherwise be impossible. It means that there are often multiple ways to solve any given problem.

The sheer number of object contexts and tags add to the complexity of the system. The gains, however, outweigh the learning curve and enable unprecedented and sometimes off-the-wall applications to take shape. You could, for instance, use the Shopp Theme API to load up a random set of products in a sliding carousel on the storefront landing page, or ditch the grid or list view layouts delivered in the starter templates for your own Pinterest-style column layout.

Unprecedented Extensibility

Beyond the built-in contexts, the structural consitency of the Shopp Theme API means that it’s possible to design your own custom object contexts and custom tags for Shopp. This is perfect for creating project-specific tags that add custom functionality encapsulated and maintained in modular code that can live safely outside of Shopp plugin code that could get replaced by updates.

The design of the system makes it easy to create Shopp-like template tags that look natural in the template files, taking care of namespacing and making it all filterable from the start so other developers can take your work even further when needed.

The final installment in this series looks at some tips and tricks to make the most out of the Theme API that will make you a pro in no time.

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