• Hardware stores selling pre-defined quantities of screws or nails
• Catering supply businesses selling large numbers of disposable knives and forks
• Other businesses selling mass produced items to retailers

In this tutorial I am going to look at a scenario where the merchant is using Shopp[1] to power their online store and where they have set up bulk items by leveraging product variants. To simulate this I created a product called Door Knockers which I am hypothetically selling to hardware stores, letting them order palettes loaded up with 100, 250 or 500 door knockers at a time.

That’s important because we aren’t letting customers specify arbitrary quantities in this scenario – we are only allowing them to buy 100, 250, 500 or whatever quantities we define.

An example I set up with a variant called Quantity, allowing door knockers to be ordered in quantities of 100, 250 or 500.

This is all very easy to set up. Simply create or edit the product in question then enable and set up a new variant (in my case I have called it Quantity) then name them accordingly. Simplicity is crucial for what we are going to do in this tutorial and here are the rules you will need to follow for every product where you set this up:

• For each product we are setting up like this we will create a variant called Quantity
• The options themselves (each reflecting a pre-defined quantity) should be named or labelled with a number – no letters or other special characters allowed
• So for a quantity of 100 items, “x100″ is a bad option name but “100″ is a good option name

Example of a “Quantity” variant where all of the option names are numbers

None of this is particularly revolutionary, it’s just a convenient way of selling bulk items in predefined quantities. As is normal, the greater the number of items purchased the greater the discount. Looking at my scenario for instance we are offering 100 door knockers for $800.00 (that’s $8 per knocker) and 500 door knockers for $2,000.00 (at this point we’re almost giving the things away at just $4 per knocker). At this point, let’s stop and look at the product on the main catalog page.

By default, variable products in Shopp have their price displayed as “From $xxx” on catalog and category views

In the context of catalog (and category) views the door knocker, as with other variable-price products, is displayed showing the least expensive option first – in this case, that’s 100 door knockers for $800.00. Our real objective here is to change this behaviour so that we see the lowest price per item ($4/knocker) instead. For all other products, we are just going to leave them untouched.

Let’s look at the category.php template and see how the price is generated.

<p class="price"> <?php shopp('product','saleprice','starting='.__('from','Shopp')); ?> </p>

Specifically we are interested in the Product Saleprice template tag. A neat thing about these tags is that they can all be filtered – and our filters can access the same information as the template tag code to make informed decisions. The logic we’re going to use in our filter is as follows:

• If there is no variant named Quantity (or just no variants at all) step back and return the default output
• Look at the price of every possible variant[2]
• Determine the price-per-unit (but only record the lowest or cheapest value)
• If we were able to determine that, return it – otherwise return the default output

And here is that logic translated into code:

/**
 * Modify the saleprice text for products with a "Quantity" variant; all other
 * products should have the saleprice returned without any changes.
 *
 * For relevant products, Quantity is assumed to contain prices with each label
 * evaluating to an integer representing quantity:
 *
 * [Quantity [ 100 => 10.00, 250 = 20.00, 500 = 40.00, ... ] ]
 *
 * This will be used to return text representing the lowest price per unit.
 *
 * @param $result
 * @param array $options
 * @param Product $product
 * @return string
 */
function custom_shopp_saleprice($result, array $options, Product $product) {
        // Load variants and variant prices
        $variants = shopp_product_variant_options($product->id);
        $prices = shopp_product_variants($product->id);

        // If no variants are set, or there is no "Quantity" variant, return the current result text
        if (!$variants or !isset($variants['Quantity'])) return $result;

        // Iterate through the variant prices and establish the lowest price-per-unit
        foreach ($prices as $variantPrice) {
                // Promoprice ought to be the current lowest price (even if there is no promo in effect)
                $cost = $variantPrice->promoprice;
                $quantity = absint($variantPrice->label);

                // Avoid scenarios where quantity is zero
                if ($quantity !== 0) {
                        // Determine the price per unit - record the lowest value as $perUnit
                        $variantPricePerUnit = $cost / $quantity;
                        if (!isset($perUnit) or $variantPricePerUnit < $perUnit)
                                $perUnit = $variantPricePerUnit;
                }
        }

        // Unable to determine a price-per-unit? Return the original result
        if (!isset($perUnit)) return $result;

        // Format and return the price-per-unit
        return sprintf('%s per item', money($perUnit));
}


/**
 * Setup our filter. We set the priority to 20 to make it run after Shopp's
 * own template tag code and the number of args to 3 because we want to pass
 * in the Product object.
 */
add_filter('shopp_tag_product_saleprice', 'custom_shopp_saleprice', 20, 3);

This can be placed inside your theme’s functions.php file (or in a plugin if you know what you are doing) and, if you need to remove it in the future, then you can simply delete it or comment it out – because it only filters the output of the Product Saleprice tag (it doesn’t change anything in the database) this is quite safe.

The end result. Door knockers and another product with a “Quantity” variant have the prices-per-unit displayed appropriately, other products are unaffected.

Any questions or problems, please just let me know in the comments.

Notes

1. In this tutorial I am working with Shopp 1.2.5.
2. We look at every variant price because we have to – if there are three variables (quantity, colour and size) each with 4 different options then there are 64 different possible prices even though there are only 4 quantities. With just a Quantity and a Color variant for example it’s easy to image an impact on per-unit pricing, such as if black door knockers are cheaper to produce than bronze-effect knockers.
3. The saleprice template tag options are fully respected only if the default output is returned. The approach used here for instance doesn’t consider taxation – but that capability could certainly be added.
4. This post was requested and generously sponsored by Josh at Ident-a-Kid Services of America

// Alter the widget title markup
add_filter('dynamic_sidebar_params', 'wrap_widget_titles', 20);

/**
 * Wrap the widget titles - including any existing before/after title markup
 * inside an extra div we can target with div.widget_title_wrapper.
 *
 * If we needed to do this selectively we could test against $widget['name']
 * or $widget['id'].
 */
function wrap_widget_titles(array $params) {
        // $params will ordinarily be an array of 2 elements, we are interested
        // only in the first element
        $widget =& $params[0];

        // Wrap the title
        $widget['before_title'] = '<div class="widget_title_wrapper">'.$widget['before_title'];
        $widget['after_title'] = $widget['after_title'] .'</div> ';

        return $params;
}

Et voila, we now have an extra box surrounding the title – which we can target with something like div.widget_title_wrapper – letting us apply a few extra effects.

What seems to be quite a common request though is to simply use the upcoming events page as a nice list view showing a specific month’s events. I’ve seen a few approaches to this but I thought I’d jot down this quick hack that allows for URLs like mycalendar.com/events/upcoming/2013-12 and then lists only events for that month and year.

function get_specified_month($uri) {
        // Look for patterns like 2099-12 at the end of the URI
        $month_pattern = '[0-9]{4}-[0-9]{2}';
        $optional_slash = '/?';
        $pattern = "#($month_pattern)($optional_slash)$#";

        // Check for matches
        $match = array();
        if (preg_match($pattern, $uri, $match) !== 1) return false;

        // We are interested only in the year/date portion
        return $match[1];
}

function upcoming_single_month_view(WP_Query $query) {
        // We are only interested in requests to view upcoming events
        if ($query->query_vars['eventDisplay'] !== 'upcoming') return;

        // Has a specific month been specified?
        $month = get_specified_month($_SERVER['REQUEST_URI']);
        if ($month === false) return;

        // Set the start date, end date
        $query->query_vars['start_date'] = $month.'-01';
        $query->query_vars['end_date'] = $month.'-31';
}

// We'll run our filter later than TribeEventsQuery::setArgsFromDisplayType()
add_filter('parse_tribe_event_query', 'upcoming_single_month_view', 20);

It really is a hack and I’ve paid no heed whatsoever to scenarios like a given month with a large number of events (and so requiring pagination) – but I do often find myself needing code like this as a quick starting point to help people out so will record it here for posterity and my own convenience  

Notes

1. The sharp eyed may note my casual assignment of 31 to form the last day of the month and wonder at my folly - February never has 31 days, after all – but as the date is used in a basic string comparison we can actually get away with this.
   
2. Spoiler alert! Though useful for The Events Calendar 2.x, some pretty major changes are apparently underway for version 3.0 so it may well be far easier to do this quite soon.

• WordPress 3.5 and Shopp 1.2.5 will form the base
• Content templates for the decorative icing
• Post functions and a humble page, because if you are doing this for a client they may want to easily change the thank you message itself – especially at or following this time of year – without having to get their hands sticky mixing code and rolling out HTML

Once a customer places an order, a confirmation email is dispatched automatically, so half the work is already done here. All we want to do is shoehorn in a little message and what we will do is use a custom template to override the default one used by Shopp.

The process of overriding default templates is covered over in the Shopp documentation quite nicely, but for anyone who is unfamiliar with this the basic idea is to create a directory named shopp within your theme directory. For instance, if your theme is Twenty Eleven then the path to any custom Shopp templates would look like this:

wp-content/themes/twentyeleven/shopp/ ...

In this case, we are going to override email-order.php so at the end of this exercise a new version of that file should live in the above folder, like so (obviously if you are using a different theme then twentyeleven isn’t going to be part of the path):

wp-content/themes/twentyeleven/shopp/email-order.php

If you’ve already installed custom templates then you may even have this file already in place. If you do, it’s contents probably look something like this:

Content-type: text/html; charset=utf-8
From: <?php shopp('purchase','email-from'); ?>
To: <?php shopp('purchase','email-to'); ?>
Subject: <?php shopp('purchase','email-subject'); ?>

<html>

<div id="header">
<h1><?php bloginfo('name'); ?></h1>
<h2><?php _e('Order','Shopp'); ?> <?php shopp('purchase','id'); ?></h2>
</div>
<div id="body">

<?php shopp('purchase','receipt'); ?>

<?php if (shopp('purchase','notpaid') && shopp('checkout','get-offline-instructions')): ?>
    <p><?php shopp('checkout','offline-instructions'); ?></p>
<?php endif; ?>

</div>

</html>

So pretty straightforward. This is an approximation of what it’s output looks like:

What I want to do here is insert a little message below the header but above the minutiae of the order itself. This can be accomplished very easily simply by inserting a snippet into the template, like so (noting the new paragraph inside div#body):

Content-type: text/html; charset=utf-8
From: <?php shopp('purchase','email-from'); ?>
To: <?php shopp('purchase','email-to'); ?>
Subject: <?php shopp('purchase','email-subject'); ?>

<html>

<div id="header">
<h1><?php bloginfo('name'); ?></h1>
<h2><?php _e('Order','Shopp'); ?> <?php shopp('purchase','id'); ?></h2>
</div>
<div id="body">

<p> We would like to thank you for placing an order with 
<em>Freshly Baked Oatcakes</em>
and wish you all the best for the festive season. </p>


<?php shopp('purchase','receipt'); ?>

<?php if (shopp('purchase','notpaid') && shopp('checkout','get-offline-instructions')): ?>
    <p><?php shopp('checkout','offline-instructions'); ?></p>
<?php endif; ?>

</div>

</html>

It’s that simple and if you are comfortable with everything described so far then that is probably all you need to know. Sometimes though it might be desirable to make the process of editing the message easier – such as if you are a designer/developer handing off the site to a client and want to empower them to make changes by themselves, without diving into a mix of HTML and PHP.

There’s quite a simple solution here. First, let’s create a new page. I’m going to call my page Email Thank You but you could name it whatever you like. We’re not going to add it to any of our menus, of course, because that’s not the role that this page is going to play. Instead, it is an easily editable way of storing our thank you message.

So, go ahead and publish the page and take note of the page ID. You can obtain this quite easily by looking at the URL query in your browser’s address bar when you are viewing the page in the editor:

http://www.your-cool-website.ca/wp-admin/post.php?post=240&action=edit

In my example, above, the page (or to be accurate post) ID is 240 and of course this is likely to be different for you. Jot this down somewhere or commit it to memory and let’s make a final pass at editing our email template:

Content-type: text/html; charset=utf-8
From: <?php shopp('purchase','email-from'); ?>
To: <?php shopp('purchase','email-to'); ?>
Subject: <?php shopp('purchase','email-subject'); ?>

<html>

<div id="header">
<h1><?php bloginfo('name'); ?></h1>
<h2><?php _e('Order','Shopp'); ?> <?php shopp('purchase','id'); ?></h2>
</div>
<div id="body">

<?php
// Load the content of our thank you page 
// (change the ID from 240 to whatever is appropriate)
$page = get_post(240); 
$message = $page->post_content;

// We'll add paragraph tags, but no other filters normally
// used on post content will be used here
$message = wpautop($message);

// And display it!
echo $message;
?>


<?php shopp('purchase','receipt'); ?>

<?php if (shopp('purchase','notpaid') && shopp('checkout','get-offline-instructions')): ?>
    <p><?php shopp('checkout','offline-instructions'); ?></p>
<?php endif; ?>

</div>

</html>

Now we are drawing in the content from our Email Thank You page – making it a snap for merchants to easily edit the thank you message. This is fairly simple and means the merchant can ensure a seasonally appropriate message is contained in all their order confirmation emails. It’s also worth considering its limitations and areas for possible improvement.

• The usual gamut of filters that are applied to post or page content are not applied here. Example: if a smiley face is inserted it will not be transformed into its corresponding emoticon graphic – and the same applies to other magical bits of filtering that happen behind the scenes.
• Embedding images (emoticons included!) in the thank you page content does not mean your customer will be able to see them. Best practice with images in emails is beyond the scope of this tutorial and actually isn’t something I have a great interest in, but for any devs with time to spare you could look at parsing out any images that have been inserted into the post content and attaching them properly.

Hopefully that provides some ideas and also gives a good feel for the process of customizing Shopp templates generally. Now, with that done all that remains is for me to wish you all a final merry christmas and a happy new year!

If you have any questions or comments, please feel free to add them below and I’ll do my best to help over a cup of eggnog.

Since caching effectively “freezes” the content of a page we obviously want to avoid this on a cart or checkout page, where it could either cause a lot of confusion for customers or – worse still – the details of a previous customer might be frozen in place until the cache clears.

Lorenzo covers this nicely, but it’s also worth thinking about widgets, such as shopping cart or login widgets. We definitely don’t want to see these being “frozen” – certainly we don’t want everyone to see a single customer’s shopping cart.

Of course, if these widgets have been added across the site then they might not be covered by the basic exceptions set up in W3TC so it’s worth bearing that in mind and giving further consideration to the positioning and use of that sort of widget, or to other methods of preventing there being cached.

Habari is one of those and with the release of version 0.9 I thought I’d spend a little time looking at what on the surface looks like it might be a lighter, cleaner blogging platform than is WordPress[1].

Installation is straightforward, just as it is with WordPress, and features a single page installer. What I liked about this was that it also gave a choice of theme and basic plugins to enable right off the bat.

When you install Habari you can select a theme and plugins to get you up and running as quickly as possible.

I opted for the new (and responsive) Wazi theme, since I had just read about it in the 0.9 announcement, and went with the default selection of plugins. One click later and my new blog was installed and active, all as easy as pie. Next, I decided to login to the dashboard and was pleasantly surprised.

I also liked the menu, complete with keyboard shortcuts for rapid access.

If you’ve used WordPress then you’ll know that the dashboard is a busy, meta-box festooned place. By contrast, Habari’s dashboard contained nothing unnecessary – it felt very clean and ordered.

The editor was just as spartan, with a title field, the editor textarea itself and an input for tags, plus save and publish buttons. Once again, this couldn’t be further removed from the WordPress post editor. However, the lack of any formatting tools (with the exception of writing paragraphs, straight out of the box you would have to type in HTML to format your documents) might be a tad uncomfortable for many.

Few assumptions are made; if you need a visual editor you will need to find and install the appropriate plugin.

Personally, I liked it and I was confident that I’d be able to find a plugin to add a few bells and whistles to the editor. This was where things started to jar a little; it may be that the community and infrastructure that has built up around WordPress has rather spoiled me and raised my expectations – but for instance Habari Extras[2] was not quite as easy to search as the WordPress plugin directory.

Now given that there are far fewer plugins in Habari Extras than there are in its WordPress equivalent you could say I was simply being lazy in not just looking through the list (which is what I did in the end) but, for instance, though I alighted on jWYSIWYG as a possible option to abstract away the need to write directly in HTML, searches for terms like visual editor or just editor didn’t yield anything, probably due to the lack of descriptions.

Installing my first plugin (jWYSIWYG) wasn’t quite pain free[3], but then I am new to Habari and there is always going to be a bit of a learning curve with a new system. That said, on this occasion it was enough to make me abandon the use of this plugin.

Some other teething problems occurred when I activated Habari Media Silo – which you will need if you want to upload images and use them in your posts in a relatively integrated fashion. Unfortunately, although I could upload images to my local silo I couldn’t insert them into the post (other than by manually typing out the image tag) . As with jWYSIWYG this was due to a Javascript error. It really was a shame as I quite liked the clear, uncluttered media handling aesthetic.

Another feature I thought showed some real potential – though I admittedly couldn’t get much out of it after just a few test posts made in quick succession – was the loupe.

This screengrab of the timeline or “loupe” is from the Habari wiki and demonstrates nicely what it does.

The loupe allows you to select a period of time you want to focus in on with just a few clicks and drag operations – clearly it has the potential to make retrieving a post from a large archive fast and easy. I couldn’t really put it through it’s paces after such a casual spot of testing but it is definitely a great concept.

All in all, Habari looks like an interesting package with a lot of potential where the bloat of WordPress is undesirable; that said my feeling is that a novice would not be at home with this unless the initial setup work was taken in hand by a developer – of course since that is anyway not uncommon when putting together a new site and so may be a moot point.

Yet there are clearly some rough edges, rough enough to be a bit of a deterrent. Even so I could imagine Habari getting under my skin, it’s got a nice aesthetic and I definitely feel encouraged to explore it further.

Notes

1. I was working with a client, a busy shop owner who needed a little coaching on how to manage their website, a month ago or two. It was a real eye opener into just how busy and crowded a place the WordPress admin environment can be – easily forgotten when you spend every day working on WordPress projects. The mental note I made that day to look for a simpler solution was, in a roundabout way, one of the reasons I decided to look at Habari.
2. Where should you look when sourcing a plugin? I found references to three different locations and felt that was a tad confusing for a Habari noob like me. Perhaps they are all interlinked or some are official and others not … but it did feel just a touch disorganized.
3. Ultimately I abandoned my attempt at using jWYSIWYG. I initially installed and activated jWYSIWYG, discovered the need to enable it on a per-user basis – which I thought was actually quite a neat feature – but after again trying to edit something I was tripped up by the fact that it’s scripts, which depend on jQuery, are enqueued before jQuery itself – so nothing happens except a JS error. In fairness, this could be a result of recent changes in the 0.9 release.

• I felt like it made things a little more complete
• Some people might be doing interesting things with their store that puts these pages in the spotlight in a way that might not be true of more run-of-the-mill installations

Easily assign titles and descriptions to virtual pages like the cart or checkout.

Version 1.5 of the plugin can be downloaded from it’s home in the WordPress plugin directory.