Shopp is designed to make it possible for programmers to implement their own Shopp Theme API “tags”, and we’re going to show you how.

Creating Your Own Theme API Tags

api_iceberg

Creating Your Own Theme API Tags

Theme API “Tag” Primer

A Theme API “tag” is not really a “tag” at all. Technically speaking, it is a PHP function provided by Shopp that acts as a gateway to all of Shopp’s theme template calls. This gateway function, shopp() uses several paramters to determine what theme template calls to make.

The Shopp Theme API borrows some conventions that WordPress uses for template tags. Similar to WordPress, the shopp() call includes an ‘options’ parameter. The difference is that WordPress template tags are all individual functions themselves that usually come in pairs with one to get the results and the other to output them to the web browser. One example of this is the_title() to output a post’s title, and it’s companion get_the_title() to get a post’s title into a local variable. This results in WordPress template tags reserving a significant amount of function names for itself. That’s OK for the core, but a plugin that has to share limited execution resources with other plugins should take care to reduce namespace conflicts before they happen.

Shopp solves this by using the shopp() gateway function to reduce the function names it uses up and protect it’s own calls from other programmers that might add their own custom functions with similar names. The consequence of this design decision means that the shopp() gateway function needs some extra information about what call to make with the options provided, including an object and a property.

shopp('object','property','options');

Put another way, you specify where to find the information, what information you want and any modifiers on the information given back.

The Object Parameter

The object parameter targets where the property information is found. This could be one of the built-in Shopp objects, or your own custom object.

The built-in Shopp object names included in the core are:

  • cart
    The shopping cart object.
  • cartitem
    An individual item (line item) in the shopping cart.
  • checkout
    The checkout form tags.
  • collection
    The product collection object which might be a custom product category, a product tag, or Shopp smart collection. You can use the alternate names category or subcategory to target the same object and help make your code more understandable in some sitautions.
  • customer
    For customer related properties.
  • error
    Targets error message properties.
  • product
    For product object property tags.
  • purchase
    For order related object property tags.
  • shipping
    For a shipping method estimate object.
  • storefront
    The generic storefront object for all storefront related calls. This object is also accessible using the object name catalog instead. Use of catalog is being actively discouraged and is mostly included for backward compatibility.

The Property Parameter

The property parameter tells Shopp what property you’re after. Each object has it’s own set of supported property tags. A complete reference is available on the Shopp API reference site.

The Options Parameter

The options parameter is used to modify the information provided by the call with several prebuilt features.

Like WordPress, options can be specified either as a string or an associative array. Strings are query-string formatted using key=value pairs separated by ampersands (&):

shopp('object','property','option1=value1&option2=value2&option3=value3...');

Options passed by associative array allow you to specify the key as the name of the option followed by the value. This is useful especially when you need to use an ampersand (&) inside a value where it would get misinterpreted in the query-string style options:

shopp('object','property',array('option1'=>'value1','option2'=>'value2','option3'=>'value3'));

All Theme API calls share a set of universal options:

  • return: when set to true, 1, or on, this option forces the tag to return the value instead of displaying/echoing the value to the page. Alternatively, prefix the tag parameter with get to get the same effect. All theme api tags that return a boolean value will return by default.
  • echo: when set to false, 0, or off, this option forces the tag to display the value to the page. This is the default for all non-boolean tags.
  • is: when set to true, 1, or on, this option will evaluate the return of the theme api call as a boolean true or false value. See how values are converted to boolean.

Boolean return values will be automatically returned.

Inside the Theme API

For PHP coders that want to quickly find what object-property tags exist can find them in under shopp/api/theme/ which contains files that handle all of the Theme API calls. Each file contains a class that acts as a namespace container for the Theme API calls.

Filtering

The shopp() Theme API gateway function acts as a controller, routing the calls to handlers using a dynamic filter hook that is of the following form: shopp_themeapi_object_property.

The filter is passed three arguments:

  1. $result
    The current returned result of the shopp template tag call
  2. $options
    An associative array of the options passed to the template tag call
  3. $Object
    The target object of the template tag

This filter can be used to override the behavior of an existing Theme API tag, or invent a completely new Theme API tag.

Example:

shopp('product','input','type=textarea&name=Engraving&cols=20&rows=3');

You could write a filter for this to change the information before it gets output to the browser or captured in a variable:

add_filter('shopp_tag_product_input','my_product_inputs_func',10, 3); // normal priority 10, and accept 3 args

function my_product_inputs_func($result, $options, $Product) {
    // TODO - write markup for my custom product input here
    return $result; // my new result
}

You aren’t limited to filters for existing Theme API calls either. You can specify a filter hook callback to support your own object-property Theme API calls to existing Shopp objects, or a custom object of your own design.

Say you have several products that have free downloads associated with them, so you want to add a property free-download that will output the link.

This could look something like:

add_filter('shopp_themeapi_product_freedownload','lookup_my_downloads',10, 3); // normal priority 10, and accept all 3 args

function lookup_my_downloads ($result, $options, $Product) {
    $classes = empty($options['class'])?'':' class="'.esc_attr($options['class']).'"';

    $downloads = array(
    "product1"=>"http://mysite/download1",
    "product2"=>"http://mysite/download2"
    );

    if (in_array($Product->slug, array_keys($downloads))) $url = $downloads[$Product->slug];

    if (isset($options['link'])) && value_is_true($options['link'])) 
        $result = '<a href="'.$url.'" $classes >'.($options['label'] ? $options['label'] : 'Download').'</a>';
    else $result = $url;

    return $result;
}

Then, in your product template, you could use your new product tag this way:

shopp('product','free-download','link=on&class=download&label=Product Download');

When viewing product1, it would output:

<a href="http://mysite/download1" class="download">Product Download</a>
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.

  1. Avatar of wbickley

    There is an extra closing bracket after the isset($options[‘link’]) which causes the code to crash.

    It’s also worth mentioning not to put hyphens in the filter name, for example I tried “add_filter( ‘shopp_themeapi_collection_is-filtered’…” but this did not work. The reason I believe is due to the fact Shopp strips the hyphen when the tag is used so that “shopp(‘collection’, ‘is-filtered’)” would be computed as “shopp(‘collection’, ‘isfiltered’)” thus never matching the added filter.

    August 29th   #

You must be logged in to post a comment.

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

Skip to toolbar