Adding Items to the Shopping Basket

Adding products to the user's shopping cart takes a few extra parameters (additional items of information that the Engine needs in order to complete its task). Obviously, you need to tell the Engine what product you are selecting, as well as its price, quantity, shipping charge/weight, description, etc.

The Engine recognizes a number of "fields" (bits of information associated with an item):

• The Item Number (required) - your product ID code; most merchants have a unique identifier (numeric or alphanumeric) which corresponds to each product - you use it in this field. It appears on your order.

• The Item Quantity (required) - the quantity of the item purchased; this can correspond to the number of products purchased, or it could be the number of "units" in which you measure the product. For example, if you're a coffee company, perhaps the "item quantity" would refer to the number of pounds of coffee ordered.

• The Unit Cost (required) - the cost per unit of your item; this is a decimal number such as "1", "2.50", "19.95", etc. It doesn't have to be in US Dollars. If you are using another monetary system (such as pounds sterling), the system can be configured to recognize that format as well.

• The Item Name (required) - this is the line-item description of your product; it will appear on any invoices or orders; when specified in a URL, you'll need to replace any spaces with understore (_) characters in order to properly transmit the data across the Internet. The maximum length is 50 characters.

• The Item Style (optional) - this is a special field which can be used more than once to "append" additional information to the Item Name; generally this field is used to specify a "style" of the aforementioned product (i.e. If a t-shirt, the size or color) - it's generally reserved for variable characteristics of the product which do not affect the price.

• The Item Freight (optional) - this is the per-item shipping charge; depending upon how you're calculating shipping, this value can have different meanings: it could be a per-unit charge, or perhaps it represents the weight of the product that when added with all other product weights is looked up in a table to determine total shipping charges.

• The Vendor ID (optional) - a Vendor ID can be specified with each item if desired - in this manner you could support one web site, which showcases products from multiple vendors and when a user makes a purchase, the Vendor ID's dictate which merchant receives orders for which products (basically a "mall" type situation where users can have multiple products from multiple merchants in the same basket - yet have a single "check-out" for everything). If the Vendor ID is not specified, it is assumed to be the main Vendor ID as referenced in the "c_MyID" command.

There are a number of ways to invoke the Engine. In order to give you maximum flexibility, we allow the ability to perform most of the Engine's functions from within a FORM as well as a stand-alone URL. In a FORM statement, you can have the user select multiple products with a single submission as well as specify quantities at the time of selection. With a URL statement, you can create clickable graphics which add items to a basket or go to the check out.

In each case, the method of sending information is slightly different as a result of the different references.

These commands are sent to the Engine in one of two ways:

• As a stand alone URL:

  <A HREF="http://order.icorp.net/mpr/mo?add+c_sample+i_10+u_1.95+q_1+n_Bob's_Bar-B-Que_Sauce ...
  (The actual commands & options are outlined in detail later)

  The static portion of the URL is: http://order.icorp.net/mpr/mo
  with a question mark "?" separating the URL from the commands. The first command is the function (in this case, "add" meaning to add the specified product to the user's shopping basket), followed by the Vendor ID, and then the fields identifying the item.

  Note that in the above example, the fields of information associated with an item are "encoded" into a single line in a special format. Once you understand how to use the tokens, you can immediately get your online store up and running.

  The fields are referenced in the format of:
  token character_field value
  (a single lowercase character, immediately followed by an underscore, immediately followed by your data)
  and each field is separated on the command line by a plus "+" sign.

  NOTE: There should be no spaces anywhere in the URL or else it won't work. If you need to specify a space in the field value, use an understore "_" character and the engine will convert it to a space later.

  The token characters are identified as follows:

  • c - Vendor ID (configuration name)
  • i - Item Number
  • u - Unit Cost
  • q - Quantity
  • n - Item Name
  • s - Item Style
  • f - Item Freight
  • v - Vendor ID (associated with each item - not required, only for "malls")

• As a FORM method:

  <FORM METHOD="post" ACTION="http://order.icorp.net/mpr/mo">
  <INPUT TYPE="hidden" NAME="c_sample" VALUE="1">
  <INPUT TYPE="hidden" NAME="function" VALUE="add">
  ...
  <INPUT TYPE="hidden" NAME="function" VALUE="add">
  <INPUT TYPE="hidden" NAME="item" VALUE="10">
  <INPUT NAME="iqty" VALUE="0">
  <INPUT TYPE="hidden" NAME="iunit" VALUE="1.95">
  <INPUT TYPE="hidden" NAME="iname" VALUE="Bob's Bar-B-Que Sauce">
  ...
  <INPUT TYPE="submit" VALUE="Add Items to my Basket">
  </FORM>
  

  As you can see, the method of specifying field values (information on your item) is slightly different when using an HTML FORM. With the exception of the Vendor ID, you spell-out the name of the fields in separate <INPUT ... > statements.

  In the above example, the first two fields specify the Vendor ID and function respectively. These are required. In the second set of fields, we specify information on the item. In this case, we've made the quantity field user-selectable - the idea being we're presenting a list of products. If the user changes the quantity from 0 to 1, it indicates they're ordering/adding the particular item. Otherwise, any item with a quantity of 0 will be ignored.

  The fields are referenced in the format of:
  <INPUT TYPE="hidden" NAME="field name" VALUE="field value">
  

  The field names are identified as follows:

  • item - Item Number
  • iqty - Quantity
  • iunit - Unit Cost
  • iname - Item Name
  • istyle - Item Style
  • ifreight - Item Freight
  • ivendor - Vendor ID (associated with each item - not required, only for "malls")

In following sections of the tutorial, you'll find numerous examples of these HTML statements and their proper usage.

Next Section: Examples with explanations