TLDR: Check the title. The documentation might be outdated.

Intro and backstory

Every programmer has those, “Aha!” moments when too much time has been spent on a problem and then the solution finally begins to surface. That moment came to me a couple of weeks ago while working on a client’s e-commerce website.

Most of our clients’ websites are built with WordPress and the e-commerce types use the Shopp Plugin (which has been great!). But, the issue seems to always come up where the plugin doesn’t exactly offer a feature the client wants. This can be said of nearly any WordPress plugin. So as a developer, we begin a depth-first search through the documentation which usually ends at a dead end and 20 tabs open in your browser.

The problem

The client wanted a set of products displayed and optionally, a personalized message attached to the product (the purchaser could add a custom message if they wanted).

Displaying products, adding customized messages, and adding a product to the cart is pretty easy with the Shopp plugin.

The Shopp Theme API offers a really convenient way for handling custom purchaser input and adding products to the cart. But, because of the way I was querying and rendering products, these options weren’t feasible. More specifically, the process of adding a product to the cart with the shopp(‘product.add-to-cart’) function wasn’t going to work in my case.

The solution – shopp_add_cart_product

The Shopp plugin has two parts to their developer API. They call one section the Theme API and the other, the Development API. The two functions listed above were out of the Theme API but I needed something different for adding products to the cart.

After sifting through the theme Development API, I come across the shopp_add_cart_product function which seemed ideal for my case. The only complex part was adding the customized message and right away, I couldn’t see an obvious way of adding it. Could I use what Shopp calls a Variant to add the customized message? I’ll save you the time and effort… No, you can’t.

More time searching…

After realizing I couldn’t handle the customized input after reading the documentation, I spent more time sifting through the documentation trying to find some hack to try and piece together a solution… I couldn’t find anything. So the question became, how does Shopp actually insert customized messages when they use their Theme API? I’d have to check the source code to find out…

To Github!

Thankfully, the Shopp plugin is open source and hosted on Github. This makes searching for things extremely helpful. So after some time searching through unit tests and following the flow of transactions through the Shopp API, I end up at the shopp_add_cart_product function again, Shopp > API > Cart.php.

At that moment, I was excited when I seen it. The function accepts 4 parameters. Could this $data variable be what I needed to store my personalized message data?

function shopp_add_cart_product ( $product = false, $quantity = 1, $variant = false, $data = array() ) {

Now compared to the official documentation, the function should accept 3 parameters with no mention of an extra $data parameter.

The function header from the documentation:

shopp_add_cart_product ( $product, $quantity, $variant )

Conclusion

This function was the right one for the job. I was able to store the personalized data with the extra $data parameter. Big woop, right?

I think more importantly, and the reason for this post, is that we can’t give up when the first, second, and third path in the depth-first search for answers fails. Obviously, every developer’s situation will be different and this might not be the case if say, you’ve already spent days or weeks trying to find a solution ( know the right time to try something else ).

If we can make an effort to make the best possible decision at every step in the search for finding an answer we can reduce the time taken to find the answer if one exists.

In my case, the high-level version of the path looked sort of like this:

Theme API > Development API > Github