Documentation

Upgrading to 1.3

A lot of work has gone into developing Octoshop 2.0 recently, and much of that has been adding awesome new features. We've also cleaned up older code for a more pleasant experience when implementing Octoshop into your own website.

To make the transition to 2.0 smoother, we're releasing 1.3. It implements many of the new bits while remaining to work with the old. You even get some new features early!

This page serves as a guide to the things that are going to change in v2. Everything mentioned here is available right now, and it's recommended that you update as soon as possible to avoid potential issues when v2 is eventually released.

TL;DR: To avoid breaking your website, update your theme now using these notes as a guideline. That way, when v2 is released with much more awesome, you can upgrade seamlessly.


Components Product Model Payments Twig Filters

Components

Basket

The paymentPage parameter is now checkoutPage. The easiest way to update this is to open your pages, layouts and/or partials in an editor.

Alternatively, *nix users can run these commands in a terminal:

$ cd /path/to/octobercms/themes
$ find . -name '*.htm' -exec sed -i 's/paymentPage/checkoutPage/g' {} \;
Product Images and Custom Fields

Some people previously had to hack the Basket component in order to get product images and other custom data to show in their website.

All product attachments, relations and attributes are now included in the available basket data as standard. This includes custom fields you may have added to the Product model from your own plugin.

Product List

To match the categories component, shopProductList is now simply shopProducts. Like the basket component's paymentPage parameter, it's best to edit files directly if you use Windows.

For the Linux/OSX people, this is much easier:

$ cd /path/to/octobercms/themes
$ find . -name '*.htm' -exec sed -i 's/\[shopProductList/\[shopProducts/g' {} \;

Product Model

Helper methods

All basic helpers that return a true or false value have been prefixed with 'is', and outOfStock has been renamed for uniformity:

  • $product->inStock()$product->isInStock()
  • $product->outOfStock()$product->isNotInStock()
  • $product->outOfStock()$product->isSoldOut()

You'll notice there are two ways to check if a product is out of stock. isSoldOut() is an alias of isNotInStock() — the result is the same.

The {{ product.getSquareThumb() }} image helper is also being removed, in favour of the |thumbnail Twig filter.

Query Scopes

The filterCategories() scope is now shorter:

$products = Product::inCategories([1, 2])->get();

Several other helpful scopes have also been added and will later be fully documented. To see what's available, check the Product model.

Stripe

To make way for more backend options, Stripe's settings model has been renamed, and the stripe_ prefix has been removed. Your API keys will be transferred automatically during the update.

If you have the following in the code section of a page...

<?php
use Feegleweb\Octoshop\Models\Settings;

function onStart()
{
    $this['key'] = Settings::get('stripe_active_keys') == 'live'
                 ? Settings::get('stripe_live_pub_key')
                 : Settings::get('stripe_test_pub_key');
}

...then you can update it like so:

<php
use Feegleweb\Octoshop\Models\StripeSettings;

function onStart()
{
    $stripe = StripeSettings::instance();
    $this['key'] = $stripe->active_keys == 'live'
                 ? $stripe->live_pub_key
                 : $stripe->test_pub_key;
}

Twig Filters

This version introduces two new Twig filters that can (and should) be used when displaying certain types of data. These filters offer a more flexible way of achieving previously cumbersome tasks.

Images (|thumbnail)

Previously, the only option was to generate a square thumbnail:

{{ product.getSquareThumb(300, product.images.first) }}

As of 1.3, this is much easier:

{{ product.images.first|thumbnail }}

By default, it will generate a 300px cropped square thumbnail. You can change the width, height, mode, quality and file extension by passing parameters in that order:

{# Generate a 150x200px exact png at 100% quality #}
{{ image|thumbnail(150, 200, 'exact', 'png', 100) }}

Once again, terminal to the rescue! This should cover most cases:

$ cd /path/to/octobercms/themes
$ find . -name '*.htm' -exec sed -i 's/{{ product.getSquareThumb(\([0-9]\+\), \(\(product.\)\?\(image\|img\)\(s\?.first\)\?\)) }}/{{ \2|thumbnail(\1) }}/g' {} \;

Prices (|currency)

Prior to 1.3, anywhere a price was shown was hard-coded to GBP. This is no longer the case; you can now configure every detail in Settings > Shop > Currency:

Once you've configured your settings, all prices shown in the backend will reflect your changes automatically. The same applies to anywhere you use the default component partials.

If you're overriding any partials that show a price, you'll want to update your code to use a format similar to this:

{{ product.price|currency }}

...and here's one final bit of shell-fu for the *nix users:

$ cd /path/to/octobercms/themes
$ find . -name '*.htm' -exec sed -i 's/&pound;{{ \(product\|item\|order\).\(price\|\(sub\)\?total\) }}/{{ \1.\2|currency }}/g' {} \;

Note if you're using a different currency, you will need to change &pound; to whichever currency symbol you're using at the moment.