Upsale Magic Module
for Miva Merchant

Version 1.00
May, 2005

by Magic Metal Productions

This document gives instructions on installing and using this module for Miva Merchant shopping-cart systems. If you need additional details, check with your Miva or hosting representative or documentation. You can also request help by email to support@TheMagicM.com.

Overview

Upsale Magic provides a discount function that allows you to set up many different variations on the idea of "buy X, get a special price on Y." This idea of using one purchase to encourage another is called "upsale." As you probably know, Miva Merchant has a built-in upsale feature, but many users find it too limited for their needs. Upsale Magic overcomes a major limitation by allowing you to inform customers of the discount while they are shopping, instead of waiting till they check out.

The module's essential features are:

Both "X" and "Y" can be a single product, or a list of products; or the discount can apply to all products in one or more categories.
The discount can be set to offer a dollar amount, a percentage, or an alternate price for the item.
You can optionally set a limit on the number of "Y" items for which the discount will apply.
You can set up many different discounts for various products.
Messages describing the discounts can be displayed to the customer as soon as they view any product for which a discount is available. (This is unlike Miva's upsale feature, which does not display the special offer until a customer is checking out of the store.) Module settings allow you to customize the message text.
The location of the discount messages can be specified by using tokens for OpenUI or for template modules.

Customer advisory
This module is designed for use by all Miva Merchant users. Some understanding of HTML coding is needed if you want to customize the discount message display, or if you want to use tokens for OpenUI or for the Viking Coders template modules. However, the module can be used effectively without knowledge of HTML or tokens.
NOTES:

You must have either OpenUI or some template modules (such as the Viking modules, or the Dynamic Template Engine from Copernicus) installed in your store to use this module. If you have none of these modules, you can still use Upsale Magic by customizing your MMUI.
To use OpenUI tokens, you must have compiled Miva (Merchant version 4.14 or higher).

Installation

The procedure for installing this module is the usual one for Miva Merchant modules: add the module to the site, and assign it to the store. The procedure is explained below in a bit more detail. If you need more information, see your Miva representative or documentation.

NOTE: If you intend to use this module with OpenUI, you should install OpenUI before installing this module.

Log in to the Miva Merchant Administration page.
In the left-side menu, click the blue triangle next to the Modules link.
Click the Add Module link.
In the right-side frame, click the Upload button.
In the Upload box, click the Browse button.
Navigate to the folder where the payment module source file, upslmagic.mv, is located, and select the file.
In the Upload box, click Upload. After a few moments, the Upload box will close.
In the right-side frame, click the Add button.

After the module is installed, you need to assign it to your store.

In the left-side menu, click the triangle next to the Stores link.
Click the triangle next to the link labeled with the name of your store.
Click the link labeled System Extension Configuration.
In the right-side frame, find the checkbox labeled Upsale Magic, and click it once (put a checkmark in the box).
Click the Update button in the lower right corner of the frame (you may need to scroll down to see it).

After the module is assigned to the store, a new "tab" link, labeled Upsale Magic, will be seen at the top of the right-side frame. Clicking this link will take you to the module's settings screen.

Operation

Upsale Magic provides two types of discounts, which we will refer to as store-wide discounts and product discounts. Both types have the same features, but they apply to different products.

The store-wide discount is set up on the module's main admin screen (in System Extension Configuration). You can enter one set of "X" and "Y" products, and one type of discount for all of them.
Product discounts are set up by clicking the Upsale Magic link in each product's screen (in the Products section of admin). In this case, the product itself is the "X," but you can specify the "Y" products and the type of discount. This gives you flexibility to set up different X-Y relationships, with different discount amounts, limits, etc.

After you have defined some discounts, the module displays discount messages on the category and product pages (and you can put them on other pages as well, if you are using tokens). For example, suppose you have a store that sells wristwatches, jewelry, and accessories; and you create a store-wide discount so that anyone who purchase a watch can also purchase an accessory at half price. In this example, the "X" is the Watches category, and the "Y" is the Accessories category.

Once you have created the discount, a discount messages will appear on the Watches category pages that looks something like this:

On the Accessories category pages, the message will have the same format, but slightly different wording:

The messages will also appear on the product pages for all applicable products:

Module settings

This section describes the use of the various text boxes and buttons on the module's settings screens for the whole store or for individual products. After changing any settings, remember to click the Update button in the lower right corner of the frame (you may need to scroll down to see it).

Store settings

These settings control the store-wide discount and the message display.

Required products
These three text boxes allow you to specify the "X" products: the ones that customers must buy to activate the discount.

You can enter one or more product codes in the Products box.
If there is an entire category, or several categories, in which you want all the products to activate the discount, you can enter the category code(s) in the Categories box.
If there are categories for which you want to enable the discount, but there are a few products that you want to exclude (prevent them from activating the discount), you can enter those product codes in the Excluded products box.

Discounted products
These three text boxes allow you to specify the "Y" products: the ones that customers can buy at a discount after they place an "X" product in their basket. There are text boxes for Products, Categories, and Excluded products, all of which function as described above for required products.

Discount settings

These settings allow you to specify the rules for the discount on the "Y" products. There is a drop-down menu to set the discount type:

No discount can be used to conveniently disable the discount without removing all the product and category settings.
Reduction in price sets the discount to be a specific dollar amount that will be deducted (subtracted) from the regular price.
Percentage off price sets the discount to be a percentage off the normal price.
Alternate price causes the "Y" products' price to be changed to the specified number. You can set a price of 0.00 to create a "Buy X, get Y free" discount. The module will display the word "FREE" if you set an alternate price of 0.00.

The Discount text box is where you enter a number to set the amount of the discount. This amount may be a reduction in price, percentage off, or alternate price, depending on the setting of the drop-down menu.

The Max. quantity text box allows you to set a limit on the number of "Y" products that a customer can purchase. For example, if the limit is set to 5, then even if a customer has 10 "X" items in their basket, they can only get a discount on 5 "Y" items; if they purchase more than 5 "Y's," they will pay the normal price for the rest.

Message locations
If you are using OpenUI hook points to display discount messages, these buttons control where the Upsale Magic discount messages will appear.

NOTE: These buttons are only operative if you are using OpenUI hook points. If you are using tokens, the locations of the tokens will control the display. (See the section on Compatibility, later in this document, for details.)

On the product pages, you can select one of six different locations, or select None to remove the messages.
On the category pages, there are more options, because there are two kinds of messages that can be displayed. There are messages that apply to the category ("Buy any item in this category, and get $10 off on YYY"); and there may also be messages that apply only to a specific product.
Discount messages for the category can be displayed at the top or bottom of the page, or in both places, by making selections from the Top and Bottom buttons. Messages for a specific product can be displayed over or under the product, as selected by the Each product buttons. Any of these messages can also be removed from the pages by selecting None.

Message display
There are two text boxes that allow you to control the discount messages that are displayed to customers when they view an "X" or "Y" product. You can put HTML formatting tags or descriptive text in the two boxes labeled HTML before messages and HTML after messages. This can be used to change the font or color of the messages, put additional text before or after them, enclose them in a table, etc.

The Template for basket rows text box is for use with some template modules, such as the Viking Coders Other Pages Templates. Upsale Magic creates discounts by putting extra "BasketCharge" entries in your shopping basket; it's the same mechanism that is used to add shipping and tax charges. The Viking module, and possibly others, do not display these BasketCharges as part of the normal Basket Contents screen.

Your customers should be able to view their discounts in the Basket Contents screen; they shouldn't have to wait till checkout to see how much they're saving. If you find that your store's Basket Contents display is not showing the Upsale Magic discounts, then you will use the basket token to provide it. (See the section on Compatibility, later in this document, for details.)

Product settings
These settings control the discount for a particular product. The admin screen for this discount is simpler than the one for store discounts. The product itself is the "X," so there are no settings for that. There are three text boxes for Products, Categories, and Excluded products; these specify the "Y" products. There is also the drop-down menu for the Discount type, and the text boxes for Discount and Max. quantity. These settings are all used in the same way as the the ones described above for the store discount.
NOTE: after setting up a product discount, if you want to turn it off, set the drop-down menu to "No discount." DON'T use the Delete button; that will delete the entire product.

Compatibility

There are three different ways to have the discount messages displayed on your store's pages: OpenUI hook points, OpenUI tokens, or module tokens. To use OpenUI hook points or tokens, you must have OpenUI installed in your store. To use module tokens, you must have template modules that can use tokens, such as those from Viking Coders or the Dynamic Template Engine from Copernicus.

OpenUI hook points

This is the simplest way to add discount messages to your store. Hook points are automatically supported by OpenUI, unless you have OpenDesigner; in that case, you may have to click a checkbox to enable the hook points. Consult your OpenUI documentation for details.

When you are using hook points, the discount messages can be displayed at various locations on the category and product pages. The locations are selected by the buttons in the Message locations section of admin (described above).

OpenUI tokens

OpenUI tokens can be used to insert discount messages anywhere you want them on the product and category pages. They are also used to update the basket-contents display. There are four functions in Upsale Magic that can be called by OpenUI tokens. For instance, to display discount messages about a specific product, you could write OpenUI tokens such as:

%DOFUNC(g.MyToken|'../../system/upslmagic.mvc'|ProdMessages())% %VAR(g.MyToken)%

The DOFUNC token calls a function in the Upsale Magic module, and places the returned HTML in a variable. The VAR token causes the variable to be displayed on the customer's screen. In the above example, the function is ProdMessages(), and the variable name is g.MyToken. The expression '../../system/upslmagic.mvc' is the path to the Upsale Magic module file in your store's Miva scripts directory. The actual path may vary from the above example, depending on your store's specific configuration.

The module provides four token functions, named ProdMessages, CatMessages, UpdateDiscount, and BasketRows. Their uses are described, along with the corresponding module tokens, in the table below. If you need more details, consult your OpenUI documentation.

Module tokens

Module tokens are used in templates that are provided by modules such as the Viking Coders template modules, or the Dynamic Template Engine from Copernicus.

For Viking templates, tokens are written in the form: %module|UpslMagic|code|%
For Copernicus templates, tokens are written in the form: %module|UpslMagic|code%

Note the difference: Copernicus tokens do not use a final pipe symbol ("|") before the final "%" character.

The code determines the text or HTML that the token will generate. Upsale Magic provides the following tokens:

Module token (in Viking format)	Function for OpenUI `DOFUNC` token	Display
`%module\|UpslMagic\|prod\|%`	`ProdMessages`	Discount messages for a specific product.
`%module\|UpslMagic\|cat\|%`	`CatMessages`	Discount messages for a category.
`%module\|UpslMagic\|update\|%`	`UpdateDiscount`	This token does not display anything; it just updates the discount data for the customer. If you are using a template to display the Basket Contents screen, you should place this token at or near the top of the template, so that it can perform its function before the customer's purchases are displayed. Also, if you are using templates for the first (OINF) or second (OSEL) checkout screens, you should place this token near the top of those templates.
`%module\|UpslMagic\|basket\|%`	`BasketRows`	Discount entries in basket. This token is for use in the Viking Other Page Templates module, and any other template that does not automatically display discount entries in the basket.

Upsale Magic Module for Miva Merchant

Version 1.00 May, 2005