Integrating Option Matrix

Front-end API for Option Matrix consists of a few functions. Use om() method to access product, cart item, or order item property instead of accessing the property directly. This article explains how to implement Option Matrix support in different areas of a store.

om() function

Shop_Product::om() function returns Option Matrix product property with automatic fallback to the base product properties. It uses currently selected product options to determine which Option Matrix product is referred. By default it loads options from POST data, but if the page is first loaded, it should know which options should be used. For example, product options could be specified in the page URL. Use Shop_ProductHelper::get_default_options() method to obtain selected product options and pass the result as the second parameter of all om() calls on the product page. Example:

$posted_options = Shop_ProductHelper::get_default_options($product);
$price = $product->om('price', $posted_options);

Please read Shop_Product::om() method reference for details.

Product page

As product parameters depend on options, product page should be reloaded when another option is selected in the option drop-down menu. That can be accomplished with adding the following onchange event handler to the options SELECT element. If you use the default basic theme, you should update shop:product_options partial.

onchange="$(this).getForm().sendRequest('on_action', {update: {'product_page': 'product_partial'}})"

Load product images from Option Matrix record, not from the base product

Use product's om() method to extract Option Matrix images. If you use the base theme, you should update product_partial partial. Update shop:image_slider render partial call:

<? $this->render_partial('shop:image_slider', array('images'=>$product->om('images', $posted_options))) ?>

Load inventory information from Option Matrix record

Use product's om() function to get inventory information. If you use the base theme, you should update product_partial partial. Replace is_out_of_stock(), in_stock and expected_availability_date calls with corresponding om() method calls:

// Replace 
$product->in_stock;
// with
$product->om('in_stock', $posted_options);

// Replace
$product->is_out_of_stock();
// with 
$product->om('is_out_of_stock', $posted_options);

// Replace
$product->expected_availability_date;
// with
$product->om('expected_availability_date', $posted_options)->format('%x');

// Replace
$product->allow_pre_order;
// with 
$product->om('allow_pre_order', $posted_options);

Use Option Matrix to extract the product's sale price and regular price

Use product's om() function to get pricing information. If you use the base theme, you should update product_partial partial:

// Replace 
$is_discounted = $product->is_on_sale(); // Previously the method name was is_discounted(), but it is deprecated now
// with
$is_discounted = $product->om('is_on_sale', $posted_options) 

// Replace
$product->price();
// with
$product->om('price', $posted_options);

// Replace
$product->get_discounted_price(1);
// with
$product->om('sale_price', $posted_options);

Handle disabled Option Matrix records

Use om('disabled') to detect whether Option Matrix record is disabled:

<? if (!$product->om('disabled', $posted_options)): ?>
  Any content placed here will be displayed only if Option Matrix record is not disabled
<? else: ?>
  <p>This product is not available</p>
<? endif ?>

Product list

In the product list you should display correct product images and price information.

Display product image

Use the product's om() method to extract Option Matrix images:

// Replace
$image_url = $product->image_url(0, 130, 130);

// with
$images = $product->om('images');
$image_url = $images->count ? $images[0]->getThumbnailPath(130, 130) : null;

Use Option Matrix to extract the product's sale price and regular price

Use product's om() function to get pricing information:

// Replace
$is_discounted = $product->is_on_sale(); // Previously the method name was is_discounted(), but it is deprecated now
// with
$is_discounted = $product->om('is_on_sale');

// Replace
$product->price();
// with
$product->om('price');

// Replace
$product->get_discounted_price(1);
// with
$product->om('sale_price');

Output associated product options

You can output associated product options. The following line outputs product options as string. It is useful on the search results page. If you were selling t-shirts the code would output t-shirt size and color as "Size: M, Color: Yellow"

<?= $product->options_as_string() ?>

Cart page

On the cart page correct product images should be displayed in the cart table (shop:cart_table partial in the default theme). Use cart item's om() method to access the product images:

// Replace
$image_url = $item->product->image_url(0, 60, 'auto');

// with
$images = $item->om('images');
$image_url = $images->count ? $images[0]->getThumbnailPath(60, 'auto') : null;

Order page

Use order item's om() method to get product's image:

// Replace
$image_url = $item->product->image_url(0, 60, 'auto');

// with
$images = $item->om('images');
$image_url = $images->count ? $images[0]->getThumbnailPath(60, 'auto') : null;

Bundle products

Use Shop_BundleHelper::get_selected_options() method to detect selected options of a bundle product. This function is similar to Shop_ProductHelper::get_default_options() described above, but it works with bundle products. The result then should be passed as a second argument for bundle item product get_price() call:

// Replace
$item_product->get_price($product)

// with
$selected_options = Shop_BundleHelper::get_selected_options($item, $item_product);
$item_product->get_price($product, $selected_options);

Changing bundle product option should refresh the bundle product partial. It could be accomplished with adding the onchange event handler to options drop-down menus. If you use Simplicity theme you should update the shop:bundle_product_options partial:

onchange="$(this).getForm().sendRequest('on_action', {update: {'product_bundle_items': 'shop:bundle'}})"

See also

• Understanding Option Matrix

Next: Creating the Search page
Previous: How to Display a Customer Order History Page
Return to Advanced Features for your Online Store