The shopp() theme api call, used throughout all Shopp theme templates, as well as used for a global “getter” interface for certain commonly used Shopp objects.

shopp( $object, $tag, $options )

@param mixed $object the string global object context name, or the Object itself.  Also, you can specify the string of the form 'object.tag' as the first argument, and omit the second argument.
@param string $tag the theme tag for the object, usually specifies a rendering function or object property
@param mixed $options (optional) options specified to the theme api call, using either a URL query style string with key=value pairs separated by ampersands, or an associative array with key=>value pairs.


The shopp() theme api call, used throughout all Shopp theme templates, as well as used for a global “getter” interface for certain commonly used Shopp objects.

Object Argument

The first argument is the object argument.

When a string is specified for this argument, the shopp() tag call is understood to be operating on Shopp’s global context, which is usually populated with an object by the page request. For instance, when the user has navigated to a specific product page, the global product context has been set by the query.

It is important when writing Shopp theme api tags into your theme template files, to know that the global context exists at the time that your theme template file will be loaded in your theme. If the context doesn’t exist, then the tag will fail to output anything, and you will likely get an error in your Shopp log. Below is a list of default contexts, and when you can expect those contexts to exist.

Built-in object contexts are:

  • catalog – after the WordPress query has been processed on Shopp related front-end pages, the catalog context usually is set. Outside of Shopp related pages, it likely will not exist.
  • category or collection – when loading a Shopp product category page, or a product collection (such as search results, product tags, smart collections), this context will be set.
  • product – when loading a specific Shopp product page, this context will be set.
  • cart – when loading the Shopp cart page, this context will be set.
  • cartitem – will not be set unless the cart has at least one item in it, and the shopp(‘cart’,’items’) iterator is being used.
  • checkout – normally used when loading the checkout and confirm-order pages, however the context is usually available on Shopp related pages (it just might not made any sense to use them).
  • shipping – normally used on the checkout and confirm-order pages. It is usually available when the checkout context is available.
  • purchase – when loading the receipt/thank you page, this context will be set. It is also set when loading the customer’s order from their account page.
  • customer – for sites where customer accounts are enabled, the context will be set after the customer logs in on the checkout form or their account page, or after a new account is created on the receipt/thank you page.

Specifying an Object
In Shopp 1.2, the object argument can also be set to an relevant Object. This is useful when you want to load and use theme api calls on an object that isn’t loaded by the page query. For instance, you can specify a Product object as the first argument, and the product context will automatically be used, however all the tags will operate on the specified Product object data, instead of the global queried product (or in some cases, when there is no product context at all).

Similarly, you can specify a ProductCategory, ProductTag, ProductCollection (such as a SmartCollection object), or ProductTaxonomy object and the category or collection context will automatically be used, only with the specified object instead of the global object context. Other contexts where it makes sense to specify an Object for the first argument are Customer and Purchase, although all the contexts can be set this way.

To illustrate, say you want to use the new Shopp 1.2 product dev api call shopp_product() to load a product, and pass that object to the theme api call. That would look like this:

// Get product 147
$Product = shopp_product(147);

// Call theme api on the loaded product, not the global product context
shopp($Product, 'name'); //display the product name in the theme layout

The last Shopp 1.2 usage for the object argument is to specify both the object and tag parameters as a string separated by a period, in the form of as object.tag. This allows you to omit the tag argument altogether (making the options argument 2nd). For instance, for the following uses are identical:

<?php shopp('product','name','return=true'); ?>
<?php shopp('', 'return=true'); ?>

Tag Argument

The second argument is the tag argument.

After the object context has been set for the shopp() call, the tag argument specifies specific content that relates to the object, such as a function that renders a menu based on the data in the object, or a particular field/property of the object that you wish to display in your theme.

An example of a tag argument would be:

<?php shopp('product', 'name'); ?>

In the above example, the tag is name, causing the name of the product to be output in the theme layout. Another example:

<?php shopp('category', 'faceted-menu'); ?>

In the above example, the tag is faceted-menu, in this case causing the category faceted menu markup to be output into the theme layout, when applicable.

Return Values
Some of the tag arguments cause a theme api call to return a value, instead of echoing into the theme layout, such as tags that are used for checking to see if a condition is true or false. For instance, see the following:

if ( shopp('category', 'has-images') ) {
// do stuff

The above example will return true or false, depending on whether or not the category has images associated with it. Check the documentation for each tag to see if it is expected return a value, or if it is expected to echo output into the theme theme layout.

Click one of the below listings of all the object context specific shopp calls, to see a listing of their related tags.

has-context tag
In Shopp 1.2, there is a special tag on all object contexts, of has-content. The has-context tag will return true when the specific object context exists (the shopp() tag can be called validly), and false when the context is not set. This can be useful when using shopp() theme api calls outside of the normal Shopp theme template that it would normally be seen, to prevent errors from occurring.

get prefix
In Shopp 1.1, when you need to have a shopp() tag return a value, versus echo output into the theme layout, you would need to use the “echo=false” or “return=true” option. In Shopp 1.2, there is a shorthand way of doing this, by specifying the prefix get or get- in front of the ordinary tag name. For example:

<?php $name = shopp('product','get-name'); ?>

The above example will cause the product name to be returned and not echoed to the theme layout. It is be the equivalent of to the following in Shopp 1.1:

<?php $name = shopp('product','name','return=true'); ?>

hyphenated or not-hyphenated
In Shopp 1.1, if the tag name was hyphenated in the Shopp source code, or source-code ;-), then you would be required to hyphenate it in your theme template. Inconsistencies in the theme api, or mis-matching which tag names were hypenated in your template would result in the call failing.

In Shopp 1.2, you can hyphenate or not hyphenate your tag name according to your preference, and the hyphens are stripped out before processing. Therefore the following are the same call:

<?php shopp('category','faceted-menu'); ?>
<?php shopp('category', 'facetedmenu'); ?>

Also the same calls:

<?php shopp('category', 'get-facetedmenu'); ?>
<?php shopp('category', 'getfacetedmenu'); ?>
<?php shopp('category', 'get-faceted-menu'); ?>

The above examples, or any combination of hyphenation, will all call the same tag, namely getfacetedmenu.

Options Argument

The third argument is the options argument.

After the tag name is specified, you may optionally pass one or more options to the shopp() theme api call, to get different behaviors from the tag. Each theme api call potentially has a different set of options, depending on the function of the tag, but the all theme api calls share a set of default options.

The default options that can be set are:

  • return – true, on, 1 to cause the theme api call to return, and not echo (echos by default)
  • echo – false, off, 0 to cause the theme api call to return, and not echo (echos by default)
  • is – will cause the tag to evaluate whether the return value of the function will evaluate to true or false in PHP. See the PHP Manual-Boolean Type for conversion results.

Theme api calls that would normally return a boolean true or false value always return (not echo).

String or Array options
Options can be specified as a URL-like query, with key=value pairs separated by ampersands, or can be specified as an associative array, with key=>value pairs.

Here is an example of the URL-like query style options, followed by the associative array style options:

<?php shopp('object','tag','option1=value1&option2=value2&option3=value3...'); ?>
<?php shopp('object','tag',array('option1'=>'value1','option2'=>'value2','option3'=>'value3')); ?>

See Also

You must be logged in to post a comment.

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