From Our Portfolio To Your Project...Buy Direct And Save!
Optional Related Products: User's Guide

Why Use Optional Related Products?

Optional Related Products is a user supported contribution for osCommerce. It adds the ability to create "relationships" between products, and the ability to display the "related" products on the product information page.

It takes a lot of time and effort, and usually some hard earned money, to get traffic to your site. You don't want visitors to immediately hit the back button and be gone. Once they view the product, if it isn't exactly what they were looking for, you still have a chance to make the sale when similar products are also listed on the page.

One size does not fit all. You know your target market and the products you sell. You should decide which additional products, if any, to display on any given product page. Automation may make things easier for you, but hand picked suggestions make a better experience for your customer. This contribution gives you that ability, and Version 4 makes it easier than ever.

Getting Started With Optional Related Products

First, of course, you need to install the contribution. Installation instructions are provided in the download archive for both New and Upgrade Installations. An SQL Setup Utility is also provided to make updating your database as easy as the click of a button. Be sure and back up your files and database before starting the installation.

After uploading the new files and making modifications to the existing files, as outlined in the installation procedures, open your Admin console and go to Catalog->Related Products. (In the left column navigation, click on Catalog. The navigation will change to display all the installed features available to maintain Catalog. Click on Related Products.)

Related Products Button
Related Products Button

The SQL Setup Utility will open automatically the first time you open this page. Select the appropriate installation option and click on the button. When the utility is finished updating your database, you will be returned to the Catalog->Related Products page.

Besides the left column navigation, you can access the Related Products admin page from the "Categories/Products" admin pages.

When a product is selected, the right column displays several buttons with management functions: edit, delete, move, copy to, and the new Related Products button. (See example image, Related Products Button, on the right.)

To manage relationships for the selected product, click on the Related Products button. The Related Products admin page opens up in a new window with the selected product as the Master, and displays any associated Slave products, as in the example image below.


[Top of Page]

How To Use Optional Related Products, A Quick Tutorial

Using this contribution is relatively straight forward and intuitive, for the most part. Let's start by defining terms used in this guide:

          Master:         Left Column (labeled A:)
          Master List:    Drop Down List in Left Column
          Slave:          Right Column (labeled B:)
          Slave List:     Drop Down List in Right Column
          Main List:      Drop Down List above the table
          <==, <==>       Symbols used to show relationship
        

The easiest way to understand how the various features and options work is to see them in action. This tutorial will walk you through the process, and demonstrate how easy it is to use.

Creating Relationships.

Master Drop-Down List
Master Drop-Down List
INSERT

Select one product from the Master List and another product from the Slave List. Click on the "Insert" button. You've just created your first Related Product record!

The page will automatically refresh and display only the products related to the Master product. For now, there is only one product.

Notice the Main List shows the Master product selected. Select the Slave product in the Main List and the page will be updated automatically.

The resulting list view, with the previous associated slave as the Master product is now empty. This is because Insert creates a one-way relationship:

Master <== Slave

RECIPROCATE
Introduced in Version 4.0

Using two products different than those used in the first record, select one product from each the Master List and Slave List. This time, click on "Reciprocate". This creates a two-way relationship between the two products:

Master <==> Slave

As before, the page refreshes and displays the list for the Master product.

From the Main List select "Show All Products".

You now have three records listed. Notice the two "reciprocated" products.

Full List Showing Reciprocated Products
Full List Showing Reciprocated Products
INHERIT
Introduced in Version 2.0

Inherit is not as straight forward as Insert or Reciprocate. Due mainly to the lack of documentation, Inherit has caused more than it's share of confusion. It is a simple concept, but not so simple to describe:

When two products are selected in the Master and Slave lists, the relationship created by Inherit is between the Master and the associated products of the Slave, but not the Slave itself.

To demonstrate Inherit, it is necessary to create multiple records with the same Master product and different Slave products. For this tutorial, use products that have not yet been used and Insert three products.

You should now see a list three records long, all with the same Master product.

Choose a new Master product, then select as the Slave the product you just created three records for. Now click on "Inherit".

Once again, you see three records listed. This new list displays the same three Slave products as the previous list, but with the new Master product.

From the Main List select "Show All Products". You now have nine records listed, including the three created earlier in the tutorial. Notice there are two Master products that each have the same related Slave products.

Full List Showing Inherited Products
Full List Showing Inherited Products

Notice the Sort Order column in the example above. The products related to the Matrox G200 MMS have a specified order. But the same products related to the Matrox G400 32MB have a Sort Order of 0 (default). While the products were Inherited, their Sort Order was not.

Duplicate Records. Version 4.0 will not create duplicate records. However, it doesn't remove duplicate records from existing data created by previous versions.

Managing Relationships.

Sort Order. The Sort Order affects the display of related products on the Product Info page. The default behaviour displays products first by their sort order, then by their record ID, (that is, the order in which the relationship was created.)

  • If the Sort Order is not specified during an operation (Insert, Reciprocate, Inherit,) the Sort Order is set to zero.
  • If the Sort Order is set during Reciprocate, both associations will have the same sort order.
  • If the Sort Order is set during Inherit, all the associations will have the same sort order.

The Sort Order can be set to Random. See 'Configuration Options'.

Edit. Once a relationship is created, it can be modified. Click on the word "Edit" for any of the existing records. Make your changes and click on "Update" to save. Changes can be dismissed by clicking on "Cancel". Changes will also be disreguarded if other records are accessed (edit, delete) without clicking on "Update".

Delete. To remove a record, click on "Delete". Default behaviour provides a confirmation box which will "pop up". You must click on OK to confirm the Delete.

Confirmation can be suppressed. See 'Configuration Options'.

Note: Records are deleted automatically when a product is removed from the database.

[Top of Page]

Option Descriptions

In early versions of Optional Related Products, the only configuration option was whether or not to display the Thumbnail Image. With Version 4.0, you now specify each of the product details to be displayed, and you can even include a Buy Now button with each product.

Display Thumbnail Images: True or False. A True setting displays the product Thumbnail Image.

Display Product Name: True or False. A True setting displays the full product name.

Display Product Model: True or False. A True setting displays the model number of the product. If set to True, but no model number exists, an empty line will be displayed. When used with Display Product Name set to True, Model is displayed inline with Name. (see Display Name & Model Variations, below

Display Price: True or False. A True setting displays the product price along with text defined in the corresponding language file, product_info.php. (See Display Price Variations, below.)

Display Quantity Available: True or False. A True setting displays the product quantity along with text defined in the corresponding language file, product_info.php. (See Display Quantity Variations, below.)

Display Buy Now Button: True or False. A True setting displays a 'Buy Now' button, allowing the customer to add the product to their cart. This function behaves the same as the standard 'Buy Now'. (See Buy Now Button, below.)

[Options List] [Top of Page]

Starting in June 2005, related products were displayed horizontally from left to right, often forcing the page to expand to fit the number of products. Version 3.3 added more control over the horizontal display:

Split Display Into Rows: True or False. A True setting uses the numeric value of 'Define Number of Items Per Row' to determine where to split the related products into rows.

Define Number Of Items Per Row: Numeric. When 'Split Display Into Rows' is True, this option controls the number of items displayed per row. When 'Split Display Into Rows' is False, this value is ignored.

Define Number Of Items To Display: Numeric. Allows you to control the maximum number of related products displayed on the product page. A value of 0 allows all related products to display.

Use Random Display Order: True or False. A True setting randomizes the display of products, and is recommended when 'Define Number of Items to Display' is greater than 0.

[Options List] [Top of Page]

Version 4.0 adds Admin options that allow you to customize the display and functions of your Related Products management page.

Admin Display: Maximum Rows: Numeric. Displays up to this maximum number of records per page.

Admin Display: Drop-Down List Maximum Length: Numeric. Set the maximum number of characters displayed of the Product Name. Allows you to truncate long names to keep the page from expanding beyond the width of your monitor. Only affects the drop-down list. A value of 0 disables this option.

Admin Display: Display List Maximum Length: Numeric. Similar to the above option, sets the maximum number of characters displayed of the Product Name. Allows you to truncate long names to keep the page from expanding beyond the width of your monitor. Only affects the standard browse list. A value of 0 disables this option.

Admin Display: Use Product Model: True or False. Set to True to display the Product Model in your lists. When used along with Product Name, Product Model is displayed first.

Admin Display: Use Product Name: True or False. Set to True to display the Product Name in your lists. When used along with Product Model, Product Model is displayed first.

Admin Display: Combine Model And Name Separator: Alpha. When using Product Model and Product Name, this character will be used as a separator. For example, a colon (':') would be a common separator character. The code places a space between the two automatically. This option can be left blank.

Admin Function: Use Delete Confirmation: True or False. If set to True, a confirmation box displaying the two products involved will appear asking if you really want to delete the record. If set to False, the record will immediately be deleted and the page refreshed.

Admin Function: Combine Insert With Inherit: True or False. Set to True, this option combines the two operations into one process. Insert button will only insert the association; Inherit button will Insert and Inherit the associations.

[Options List] [Top of Page]

Additional Display Control

Model, Price, Quantity and the Buy Now button have been setup to provide for further display control, allowing you to tweak the text and/or create a unique graphic for the Buy Now button.

Display Name & Model Variations

        define('RELATED_PRODUCTS_MODEL_COMBO', ' (%s)');

When Name and Model are used together, the two fields are displayed together in the same paragraph tag. Using the Model constant added to the language file during installation, you can change the default display, which places the model inside parentheses following the product name. The %s in the argument is a place holder for the Model string and must be included in any changes. For example, to change the display to Name: Model, edit the 2nd argument to ': %s'.

Display Price Variations

        define('RELATED_PRODUCTS_PRICE_TEXT', '@ %s');

Using the Price constant added to the language file during installation, you can surround the price with wording that makes sense for your store by editing the 2nd argument. The %s in the argument is a place holder for the Price, which includes the currency symbol. To display just the price, change the second argument to just '%s'. If your products have a range of prices, you might change the argument to 'Starting from %s' or just 'From %s'.

Display Quantity Variations

        define('RELATED_PRODUCTS_QUANTITY_TEXT', 'Only %s left!');

Using the Quantity constant added to the language file during installation, editing the 2nd argument lets you display the quantity in a descriptive manner. While the Price needs no explanation, the quantity by itself would be confusing. The %s in the argument is a place holder for the Quantity. For example, to let the visitor know they aren't wasting their time, you might change the argument to '%s In Stock'. Whatever works best for you and your products.

Buy Now Button

Included Buy Now button

A separate Buy Now graphic is provided, giving you the flexibility of using a different graphic without affecting the original Buy Now button. Create your new button in any graphics editor and save into the appropriate language button directory as button_rp_buy_now.gif.

[Options List] [Top of Page]

Special Thanks To Beta Testers

I would like to send out a great big thank you to the community members who donated their time to test the code and install procedures to help make this release easy to install and easy to use: Baddog (http://www.baddogservices.com/), MagickWomyn (No live site. Yet.), Get-Wireless 2 (http://www.get-wireless.co.uk), and jkuse (http://www.pearlstonejewelry.com).

I would also like to thank mark27uk3 (http://www.24-7mobileaccessories.co.uk/). Mark is running the Graphical Borders contribution, and needed help altering the code from Optional Related Products Ver 3.3 to support Graphical Borders. Together, we got Ver 3.3 working. When Ver 4.0 was complete, MagickWomyn and I worked together to blend the changes of 4.0 with the existing support for Graphical Borders. The results are an alternate [catalog/]includes/modules/optional_related_products.php file. Change this one file in the install, and Optional Related Products is completely compatible with Graphical Borders 2.1.