Oscommerce Related Products

Add-on for 2.2
The information below is specific to MS2.2. See notes on X-Sell for later versions.
The instructions below are no less clunky than the add-on, but it works just fine. Like all things Oscommerce – persevere!

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 the Catalog. Click on Related Products.

You can also 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. To manage relationships for the selected product, click on the Related Products button and the Related Products admin page opens up with the selected product as the Master, and displays any associated Slave products.

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.

INSERT: Select one product from each the Master List and Slave List and click on the “Insert” button.

The page will now 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: Using different products 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.

INHERIT: 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, and select as the Slave, the product you just create 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.

Inherit creates multiple one-way relationships, but does not create a relationship with the Slave product.

From the Main List select “Show All Products”.

You now have nine records listed.

-Managing Relationships.

SORT ORDER: If “Sort Order” is not specified, the record will be assigned 0 by default. If you include a value when using Inherit, all records created by the operation will have the same value. By default, products are displayed by Sort Order on the Product Information page. See OPTIONS for more information.

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 dismissed if other records are accessed without clicking on “Update”.

DELETE: To remove a record, click on “Delete”. A confirmation box will “pop up” and you must click on OK to confirm the Delete. See OPTIONS for more information.

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

** Configuration Options **

Optional Related Products has several options, allowing you to customize the look on the product page, or the functions in the Admin. All Admin options are identified as Admin Display or Admin Function.

The options are:
Display Thumbnail Images
Display Product Name
Display Product Model
Display Price
Display Quantity Available
Display Buy Now Button
Split Display Into Rows
Define Number of Items Per Row
Define Number of Items to Display
Use Random Display Order
Admin Display: Maximum Rows
Admin Display: Drop-Down List Maximum Length
Admin Display: Display List Maximum Length
Admin Display: Use Product Model
Admin Display: Use Product Name
Admin Display: Combine Model and Name separator
Admin Function: Use Delete Confirmation
Admin Function: Combine Insert with Inherit

-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.)

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.

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.

** 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

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.