Fractional product quantity & quantity units in design themes

Shop-Script licenses functionality

Shop-Script is released in two licenses with different functionality—PRO & Premium. Fractional product quantity & quantity units are available only with the PREMIUM license.

The support for this functionality in a Shop-Script design theme must be declared as described in the documentation.

Arbitrary product quantity units

Product quantities displayed in the storefront can be expressed in any units of your choice. Next to the product price must be written the name of the quantity unit for which the price is displayed.

Two quantity units, with their corresponding prices, for convenient products comparison

In this case a product has two prices—the price per stock unit, in which actually sold product quantity is counted, and the price per base unit, which can be used for convenient product comparison or filtering. Both prices, for each of the quantity units, must be displayed in the storefront, as well as the conversion ratio between them.

Sorting & filtering of products by the prices of different quantity units

If a category contains products with different quantity units then a customer can select any of those units which is most convenient for filtering or sorting products in a particular case.

Custom product add-to-cart step

For each product, an individual add-to-cart step can be set so that customers can add only quantities, divisible by the specified step value, to the shopping cart. For weight products, the add-to-cart step may be set to 0.01 lb., or to 8.5 sq. ft. for ceramic tiles (quantity contained in an individual package).

Minimum orderable product quantity

For each product, a minimum quantity can be set, below which cannot be added by customers to the shopping cart. For example, 0.3 m for fabrics sold by linear feet, or 0.5 kg for fruits and vegetables, which are sold by weight.

Variables

Product quantity & quantity units settings

A design them can obtain information on the current online store settings.

$fractional_config: associative array with settings values in the form of entries with the following keys:

Available quantity units

Information on quantity units, for use in the storefront, available as an array containing sub-arrays of individual units’ data accessible by numeric unit IDs corresponding to main array’s keys.

• $units: array of available units in a full format, each unit represented by a nested associative array with the following keys:
  • id: numeric ID,
  • short_name: 3-letter code,
  • name: full name,
  • storefront_name: formatted brief name to be displayed in the storefront,
  • sort: sorting priority,
  • status: flag denoting whether the unit is enabled in store settings,
  • builtin: flag denoting whether the unit is a system one.
• $formatted_units: array of available units in a simplified format, each unit represented by a nested associative array with the following keys:
  • id: numeric ID,
  • name_short: formatted brief name to be displayed in the storefront,
  • name: full name

Displaying of product prices & quantity units

All product prices must be displayed with their corresponding quantity units.

A product always has a price per its stock unit considered the main product price.

Also a price per base unit can be specified in the product properties, which is optional setup. If that price is set then a design theme must display the conversion ratio value between the stock unit and the base unit, also set in the product properties.

Helper method to return a formatted price with a quantity unit name

Useful to correctly display a product price with a certain quantity unit’s name, with the current user locale taken into account.

{$wa->shop->formatPrice($price, ['currency' => '...', 'unit' => '...'])}

Parameters

• $price: numeric price value.
• $params: array of quantity unit properties, with the following keys:
  • currency: 3-letter currency ID such as USD or EUR.
  • unit: localized brief quantity unit name, which can be obtained from the $formatted_units array, with the required unit’s ID used as the key.

Stock quantity unit

This unit is always available in the product properties, and it is common for all its variants.

Obtaining values

• $product['stock_unit_id']: stock unit ID specified for a certain product,
• $formatted_units[$product['stock_unit_id']]: stock unit properties from the $formatted_units array described above in the “Available quantity units” section.

Price per stock unit

Current variant’s price. This price is always available in the product properties, its value is defined by the product variant currently selected by a user. Must be displayed with a stock quantity unit name.

Obtaining a value with a quantity unit name

Using the $wa->shop->formatPrice() helper.

$wa->shop->formatPrice(
    $sku['price'],
    [
        'unit' => $formatted_units[$product['stock_unit_id']]['name_short'],
        'currency' => $wa->shop->currency()
    ]
)

Compare price per stock unit

Must be displayed, if available in the variant properties, with the stock quantity unit name.

Obtaining a value with a quantity unit name

Using the $wa->shop->formatPrice() helper.

$wa->shop->formatPrice(
    $sku['compare_price'],
    [
        'unit' => $formatted_units[$product['stock_unit_id']]['name_short'],
        'currency' => $wa->shop->currency()
    ]
)

Base quantity unit

Specified for an entire product and common for all its variants.

Obtaining values

• $product['base_unit_id': stock unit ID specified for a certain product,
• $formatted_units[$product['base_unit_id']]: stock unit properties from the $formatted_units array described above in the “Available quantity units” section.

There are two product states connected to a base unit value:

1. No base unit is set in the product properties. The value provided by the PHP code is either empty or equal to the product’s stock quantity unit. In this case the $product['base_unit_id'] variable either is missing or is equal to the value of the $product['stock_unit_id'] variable.
2. A base unit is set in the product properties. The value provided by the PHP code is neither empty nor equal to the product’s stock quantity unit. In this case the $product['base_unit_id'] variable either is not empty and not equal to that of the $product['stock_unit_id'] variable.

Conversion ration between stock & base quantity units

Specified for individual product variants. Must be displayed in the storefront is a base unit is set in the product properties, i.e. if the $product['base_unit_id'] variable is not empty and not equal to the value of the $product['stock_unit_id'] variable.

Obtaining value

$sku['stock_base_ratio']

Price per base unit

Must be displayed, with the base quantity unit name, if set in the product properties, i.e. if the $product['base_unit_id'] variable is not empty and not equal to the value of the $product['stock_unit_id'] variable.

A specific value to be displayed is individual for each product variant and is displayed with the corresponding base quantity unit name.

The product price per base unit must be calculated by a design theme as a division of the price per stock unit by the units conversion ratio, i.e. by the formula $sku['price'] / $sku['stock_base_ratio'].

Obtaining a value with a quantity unit name

Using the $wa->shop->formatPrice() helper.

$wa->shop->formatPrice(
    $sku['price'] / $sku['stock_base_ratio'],
    [
        'unit' => $formatted_units[$product['base_unit_id']]['name_short'],
        'currency' => $wa->shop->currency()
    ]
)

Compare price per base unit

Must be displayed if a base unit set in the product properties, i.e. if the $product['base_unit_id'] variable is not empty and not equal to the value of the $product['stock_unit_id'] variable.

A specific value to be displayed is individual for each product variant and is displayed with the corresponding base quantity unit name.

The product price per base unit must be calculated by a design theme as a division of the price per stock unit by the units conversion ratio, i.e. by the formula $sku['compare_price'] / $sku['stock_base_ratio'].

Obtaining a value with a quantity unit name

$wa->shop->formatPrice(
    $sku['compare_price'] / $sku['stock_base_ratio'],
    [
        'unit' => $formatted_units[$product['base_unit_id']]['name_short'],
        'currency' => $wa->shop->currency()
    ]
)

Product add-to-cart parameters

Add-to-cart step

Not displayed in the storefront.

Must be used for the functioning of elements used for adding product to the shopping cart. Specified for an entire product and is common for all its variants.

Obtaining value

$product['order_multiplicity_factor']

Quantity adjustment value via “+/-” buttons

Must be displayed next to the buttons used for changing the quantity of a product before it is added to the cart and is defined by a selected product variant.

Obtaining value

$sku['order_count_step']

Minimum orderable product quantity

Must be used for the functioning of elements used for adding product to the shopping cart and is defined by a selected product variant.

Obtaining value

$sku['order_count_min']

Maximum orderable product quantity

Must be used for the functioning of elements used for adding product to the shopping cart if the store settings can prevent a product from being added to the shopping cart depending on its stock quantity.

Obtaining value

$sku.count|default:0

Elements used for adding product to the shopping cart

A text field with “+/-” buttons used to reduce and increase the field value and with the option for a user to manually edit the field value. Must be displayed on individual product-viewing pages and in product listings where a user is given the option to add products to the shopping cart.

If product quantity adjustment value via “+/-” buttons specified in the product variant properties is different from 1 then that value must be displayed next to the “+/-” buttons.

The name of a stock unit name must be displayed above or below the quantity field.

Processing manually entered product quantity

• Round the entered value up to the nearest number which dividable without a remainder by the add-to-cart step value specif in the product properties.
• If the rounding result is less than the minimum orderable quantity specified in the product variant properties then the field value must be replaced by than the minimum orderable value.
• If a maximum orderable quantity is available and the rounding result is greater than the maximum orderable quantity then the field value must be replaced by than the maximum orderable value.

Processing clicks on the “+/-” buttons

• Reduce or increase the quantity field value by the value specified for the “+/-” buttons in the product variant properties.
• If the result is less than the minimum orderable quantity specified in the product variant properties then the field value must be replaced by than the minimum orderable value.
• If a maximum orderable quantity is available and the result is greater than the maximum orderable quantity then the field value must be replaced by than the maximum orderable value.

Updating the captions of “+/-” buttons depending on the current product quantity field value

• If the sum of the minimum orderable quantity specified in the product variant properties and the quantity adjustment value via “+/-” buttons is greater than the field value then caption “min. [minimum quantity]” must be displayed. Otherwise the “-” (minus) character or its equivalent must be displayed.
• If a maximum orderable quantity is available for a product variant, and the difference of the maximum orderable quantity and the quantity adjustment value via “+/-” buttons is less than the field value then caption “max. [maximum quantity]” must be displayed. Otherwise the “+” (plus) character or its equivalent must be displayed.

Product stock quantity information

If the use of different quantity units is enabled then the product stock quantity, when expressed by a number, must be displayed with a stock quantity unit name. Otherwise, the displaying of a quantity unit name is optional.

Product filtering & sorting on category pages

Quantity unit names must be displayed in the product filtering and sorting elements only if the use of different stock quantity units is enabled as opposed to standard pieces.

Variables

Available in product category pages’ template files.

• $filter_units: array containing full information about all quantity units available in the filter settings,
• $formatted_filter_units: array containing brief information about all quantity units available in the filter settings,
• $filter_stock_units: array containing full information about the stock quantity units available in the filter settings,
• $filter_base_units: array containing full information about the base quantity units available in the filter settings.

Filter form

• If only 1 stock quantity unit is available in a current product category
  Display the name of the available quantity unit next to price filtering fields.
• If 1 stock quantity unit and several base units are available in a current product category
  Display quantity unit selection elements next to price filtering fields. The stock unit must be selected by default. The list of available quantity units must contain the names of all units specified in the properties of the products contained in a current category. Option named like “no quantity unit” must not be available for selection.
• If several stock quantity units and any number of base units are available in a current product category
  Display quantity unit selection elements next to price filtering fields. The list of available quantity units must contain the names of all units specified in the properties of the products contained in a current category. Option named like “no quantity unit” must be available for selection and pre-selected by default.

Product sorting

• If only 1 stock quantity unit is available in a current product category
  Do not display the stock quantity unit name for the price sorting option.
• If 1 stock quantity unit and several base units are available in a current product category
  Display sorting options by the prices per all quantity units, specified in the properties of all products contained in a current category, with the names like “by price per [unit name]”.
• If several stock quantity units and any number of base units are available in a current product category
  Display sorting options:
  • by price,
  • by the prices per all quantity units, specified in the properties of all products contained in a current category, with the names like “by price per [unit name]”.

Checkout

In-cart checkout

The displaying of quantity unit names and the elements used for altering the product quantity is managed by the Shop-Script core algorithm and cannot be affected by a design theme. If necessary, a design theme can only change the appearance of such elements.

Multi-step checkout

Stock quantity unit

• If the use of different quantity units is disabled then do not display the unit name.
• If the use of different quantity units is enabled then display the unit name:
  • next to the price per stock quantity unit,
  • inside the product quantity adjustment field.