Shopping Cart Service
Features
FAQ's
Demo Store
Pricing Plans
Setup Instructions

virtualCATALOG^TM User's Guide

INSTALLATION

The PERL script, CatalogMgr.pl, the .html templates for page generation, the .key and .cfg files must be installed on your Web server in the cgibin directory. The database files will also reside in this directory. Your Web server must have PERL version 5.004_04 or later and the CGI.pm library. Contact your Web site host if you have questions regarding this installation. 

Installing VirtualCatalog isn't really difficult. The only difficult part would be installing the required perl modules if they aren't already installed or you're not installing a binary package of VirtualCatalog.

Before installing, talk your your web site administrator and find out if your web site host has the proper version of perl installed or if any of the other perl modules need to be installed. Once all of the requirements are met, then you're ready to install and use VirtualCatalog.

Unpack the VirtualCatalog distribution and carefully read the VirtualCatalog User guide in the docs directory.

Rename all ``b-xxxx'' files in the cgi-bin directory replacing the xxxx with your VirtualCart ID. For example, if your VirtualCart ID was b-2400, then rename ``b-xxxx.cfg'' to ``b-2400.cfg''.

Upload the entire directory and all of its contents to your web server in the cgi-bin directory.

CatalogMgr.pl and "b-xxxx" files must have permissions to be executable and the data subdirectory must be readable and writable by the web server. Permissions should be set to 777 for all b-xxxx files and to 766 for the CatalogMgr.pl.

The vc_login.htm should be placed in the same directory as you html files so it can be located either on your local machine or on your web site. For security purposes, it is preferable to locate it on your local machine.

Before viewing vc_login.htm in a browser for the first time it must be modified. Edit vc_login.htm with your editor of choice, either HTML or plain text. The <form> action
(action="http://yourdomain/cgi-bin/VirtualCatalog/CatalogMgr.pl") must be changed to reflect the location on your web server where CatalogMgr.pl is installed. This area of code is marked with a comment indicating what needs to be modified.

GETTING STARTED

To begin generating catalog pages with VirtualCatalog you will need to do the following things:

• Create a catalog page template and upload it to your web server
• Create an HTML page that contains a call to CatalogMgr to generate catalog pages. Upload this html file to your web site.
• Create a database of items for your catalog. You may do this by entering each record with the CatalogMgr Add Data option, or by uploading a delimited ASCII file to your web server, then using the CatalogMgr Import Data option to add the records in the file to the database.

CATALOG TEMPLATE PAGES

Catalog page templates define the format of the generated catalog pages. Use standard HTML, virtualCART coding and the specially defined VirtualCatalog substitution codes to create templates that define your catalog pages. Catalog templates should be placed in the HTX sub directory of VirtualCatalog on your web server.

VirtualCatalog template page substitution codes:
 
 

Code	Substitution Made
%cartID%	The virtualCART ID value.
%description%	The description field of the current database record.
%detail%	The detail field of the current database record.
%displayNumber%	The number of database records to display per page.
%footer%	The ftr parameter or contents of ftrFile passed to CatalogMgr.pl.
%header%	The hdr parameter or contents of hdrFile passed to CatalogMgr.pl.
%image%	The image field of the current database record.
%insurance%	The insurance field of the current database record.
%itemEnd%	A flag to indicate the end of a catalog item. All formatting contained between %itemStart% and %itemEnd% is repeated for each database record matching the search criteria.
%itemStart%	A flag to indicate the beginning of a catalog item. All formatting contained between %itemStart% and %itemEnd% is repeated for each database record matching the search criteria. The formatting between these two codes should include the HTML <FORM> code for virtualCART. (See http://www.virtualcart.com/setup.html for the details)
%matchCount%	The number of records found matching the search criteria.
%measure%	The measure field of the current database record.
%nextEnd%	A flag indicating the end of the formatting code used for displaying the "next page" option.
%nextOffset%	The offset number for the first record to be displayed on the next catalog page. Record numbers begin with 1.
%nextStart%	A flag indicating the beginning of the formatting code used for displaying the next page option. If there are no more records, the "next page" option will not be displayed.
%op1% thru %op16%	The op# fields of the current database record.
%partnumber%	The partnumber field of the current database record.
%previousEnd%	A flag indicating the end of the formatting code used for displaying the "previous page" option.
%previousOffset%	The offset number for the first record to be displayed on the previous catalog page. Record numbers begin with 1.
%previousStart%	A flag indicating the beginning of the formatting code used for displaying the previous page option. If the current page display begins with record 1, the "previous page" option is not displayed.
%price%	The price field of the current database record.
%quantity%	The quantity field of the current database record.
%searchField%	The current searchField value.
%searchFor%	The current searchFor value.
%shipping%	The shipping field of the current database record.
%weight%	The weight field of the current database record.

CatalogMgr

CatalogMgr.pl operates in two modes: configuration/data management and catalog page generation.

Using CatalogMgr from vc_login.htm will access the configuration/data management mode. Start a browser session and open vc_login.htm. After you login from the vc_login page, option pages are displayed with clear instructions to guide you through:

• changing configuration items (password, default values, etc.)
• adding records to the database
• deleting records from the database
• modifying records in the database
• importing data from a delimited ASCII file
• viewing existing database records

http://mywebsite/cgi-bin/VirtualCatalog/CatalogMgr.pl?
cartID=b2400&template=myPageTemplate.htx
&hdr=My+Online+Shopping+Site
 
 

Parameter	Value	Required
CartID	Your virtualCART ID.	yes
displayNumber	The maximum number of catalog items to be displayed on a page. If not specified, the default value is taken from the configuration file.	no
Ftr	The text to be substituted for %footer%.	no
FtrFile	A file containing the text to be substituted for %footer%.	no
Hdr	The text to be substituted for %header%.	no
HdrFile	A file containing the text to be substituted for %header%.	no
Offset	The number of the record to begin this page’s display with. If not specified defaults to 1.	no
SearchField	The database field to search in. If this field is not specified, all fields in the database are searched.	no
SearchFor	The expression to be matched in the searchField. If this value is not specified, all records in the database are returned.	no
Template	The name of the Catalog Page Generation template file. It should be given relative to the location on the web server where CatalogMgr is installed.	yes

Using CatalogMgr

Concise instructions are found on each screen. Any user actions that are necessary are explained on the screen where the action takes place.

Logging On

CatalogMgr is designed for a single-user. To begin working on the database or to change any configuration values, the user must log on. vc_login.htm must be opened in a browser. This will bring up a login screen. The Cart ID number and the Password need to be entered before any work can be done. The default password for the first login is admin. Upon successful entry of the ID and Password, an option screen that gives a choice of making configuration changes or doing database administration will be displayed.

Only one user at a time can make changes to the database or the configuration file. If a second user successfully logs in, the first user will not be able to make any more changes to the configuration file or the database. The first user will receive a timeout error if he tries to make any additions or changes after the other user has logged in. 

If a currently logged in user does not do any work for 15 minutes, they will receive a timeout error when they try to continue using CatalogMgr. If a timeout message is received, it will be necessary to go through the login process again before any work can be done.

Configuration

The Configuration screen offers forms for changing the current password and changing any defaults that are currently being used. Only one of the forms can be used at a time. To access the Configuration screen, you must log into CatalogMgr. The default password, needed for logging into the database management portion of CatalogMgr, is admin. This password should be changed before you begin to create a database. Change the password by logging in, using admin as the password, and then selecting the Configuration option. 

To change the password, enter a new password, then enter it again as indicated on the form. Then select the Change Password option. A "Password changed" message will be shown on successful completion.

The Configuration screen allows for adjustment of the number of records displayed per catalog page. You can enter a default number that will produce an effective display for your product on an average catalog page. The templates you design can over-ride this value by using the displayNumber parameter. This allows customizing a page for any special situations. 
 
 

Data Management

Choosing the Data Management option allows you to create or change the database records of the products that will be displayed on your catalog pages. The main Data Management screen offers the following database options: Add Data, Modify Record, Delete Record, Import Data, and View Data. Some of these options, such as Modify Record, can use additional information. Additional data can be specified on this screen: a search field and/or a specific string to search for. The default field is the Product Number. This will always be selected unless another choice is made. The default field is ignored when not needed by the chosen option.

When the Product Number field on Data Management is used to find records for modifying, deleting, or viewing, either a complete or partial product number may be entered. Searching involves using PERL regular expressions, so a little knowledge about these regular expressions can make searches more accurate or efficient. Entering MUS will find all products with numbers that contain MUS, such as MUS-192 or T23MUS. To find product numbers that begin with a certain character or expression, begin the search expression with ^. For example, ^MUS would find MUS-345 and MUSIC23. It would not find 105-MUS or 23MUS11. ^9 would find all numbers that started with 9.

Product numbers that end in 7 could be found by entering 7$. This would return records with product numbers like 777777, 000007, b-007, or xyzcorp-977.

Add Data

The Add Data option does not require any additional information. Simply click the Add Data button to access the Add A Record screen.

Add A Record Screen

This is the form for adding new records. Values for these fields may not contain pipes ("|"). The product number field is required and must be unique. Product number will be used as the key to the record in the database. Some fields already contain default values. These defaults may be kept or changed. Fields that are not needed may be left blank. Any virtualCART coding that will be useful, including virtualCART op# keywords may be entered in the product definition fields. HTML syntax may also be entered in appropriate fields. Look at the examples in Appendix A for more information.

The records in the database are stored in sorted order, so well thought out product numbers can make the records easier to view. Product numbers that are numeric will work, but are not the best choice. If numeric product numbers are all padded to be the same length, 0034 instead of 34, they will work better. Using product numbers that contain the same number of characters such as 000011, 000111, and CS-456, cause the records to sort in the expected order and make records easier to view.

The sequence of product numbers 1, 2, 3, 4, 5, 6,10, 11, 12,13, 20, 21, 100, 101, 111 would sort as:

1, 10, 100, 101, 11, 111, 12, 13, 2, 20, 21, 3, 4, 5, 6.
 
 

Modify Record

The Modify Record option can use additional information to help select the correct record(s) to modify. If a Search for value is entered, then a Search in fields selection should be made to determine what database field(s) will be searched. If nothing is entered in Search for, all records in the database will be shown on the Select record to modify screen. 

If a Search for value is given, CatalogMgr will try to find a match for the given value in the database field that is selected from the Search in fields list. To search for all pasta products, e.g, Product Description might be selected in Search in fields, with pasta as the Search for value. If category is chosen as the field to search, the value to search for might be "Children’s stockings", "hand tools", "tires" or whatever category is appropriate for the current catalog. If there is exactly one record that meets the selection criteria, the Modify This Record screen will show that record. Otherwise the Select record to modify screen will show all matches that were found.

Click the Modify Record button to reach one of the modify screens. Enter or change values on the Modify This Record screen just as you would on the Add A Record screen.

Delete Record

Delete Record works much like Modify Record. Entering a value in Search for, and selecting a field, will limit the search; otherwise all records will be presented for selection. Whether a single record or a list of records matches the search criteria, the Select record(s) to delete screen will be shown. The actual record(s) to delete must be selected from the item(s) given on this screen. No records will be deleted without being selected from this screen.

Import Data

No information is required before choosing to import records into the database; just click the Import Data button. The Import Data screen can then be viewed.

Import Data Screen

Using Import Data, new records can be added, fields can be changed, or records can be replaced. With the form on this screen, data can be brought into the database from a delimited ASCII file. The file must be uploaded to the install directory on the web server before it can be imported. The filename/pathname must be given relative to the install directory. 

There are two modes for bringing new data into a file. Choosing Update current records will cause any records with matching product numbers to be edited. Any fields selected in the import file will replace those fields in the matching record in the database. Any new records in the import file will be added to the database.

Choosing Delete current records then add will remove all old records and replace them with the new records from the import file. Before beginning to import a file, it is a good idea to make a backup copy of the original database. If the wrong option was chosen, if the wrong file used, or some other problem were encountered the backup database file could be copied to restore the database, and the Import Data action could be repeated.

The delimiter character used in the import file defaults to "|". If a different delimiter is used, this default must be changed to the correct character before trying to import the file. Use "\t" if tabs are used to delimit the file.

Fields in the delimited file must not contain the character used as a delimiter for the fields. Common delimiters would be a pipe symbol ("|") or a tab. Data from an Excel spreadsheet saved as a .csv file uses a comma (",") as the delimiter. This file format is not supported. The only way that this format could be used, would be if there were no commas used in any of the fields. Excel also allows saving data as a tab delimited .txt file. This would be a better choice. 

The fields that are used in the import file must be checked on the form. If the fields in the file are in the same order as the items checked, no column numbers need to be entered. If the import file’s fields are not in the same order as the fields on the form, the number of the column containing the field needs to be entered. 

An import file might be used to update prices for some products in the database. In this case, the file might contain just two fields: product number and cost. If product number is in the first column and cost is in the second, those two fields would be checked and no numbers are needed. If the import file had 4 columns with the product number in column 1, details in column 4, and cost in column 2, then column numbers would be required. If any column numbers are required, then all of the selected import fields must have column numbers.

When all of the information is entered on the form, click the Import File Now button. If the file is successfully imported, a screen with that message will be shown, and it will contain a button to return to the Data Management screen.
 

View Data

View data works much like Modify Record. Entering a value in Search for, and selecting a field to search, will limit the search; otherwise all records will be presented. If a list of products is returned, all of the details of any product can be viewed by selecting the product, then clicking the View This Record button. A single matching record will immediately be displayed in complete form.

Appendix A

Below is a sample catalog page template, referencing HTML page and data for a catalog selling books.

Catalog Page Template

The Catalog Page Template contains HTML coding and Virtual Catalog substitution parameters:

<html>

<head>

<title>Sample Catalog Page</title>

</head>

<body>

<p align="center"><font color="#FF0000"><big><big>Sample Catalog Page</big></big></font></p>

<!-- specify HTML for the header as a parameter to CatalogMgr -->

<p align=center>%header%</p>

<blockquote>

<p><hr width=75%></p>

<!-- here is the beginning of the coding for each database record -->

<!-- this HTML will be repeated for each record, with the field -->

<!-- substitutions made -->

%itemStart%

<FORM action="http://www.cartserver.com/sc/cart.cgi" method=POST>

<INPUT TYPE="hidden" name="item" VALUE="%cartID%^%partnumber%^%description%^%price%^%quantity%^
%shipping% ^%insurance%^%measure%^%weight%^%image%">

<img src=%image% align=middle height=140 width=100>

%detail%<br>Price: %price%<br>

<INPUT align=center type=image border=0 name=add
src="http://yourdomain//ctb2.gif" width=100 height=24>

</FORM>

<p><hr width=75%></p>

%itemEnd%

<!-- end of coding for each database record -->

</blockquote>

<!-- the following code places the check-out and view catalog images and code at the bottom of the page -->

<table align=center>

<tr>

<td>

<FORM action="http://www.cartserver.com/sc/cart.cgi" method=POST>

</td>

<td>

<INPUT TYPE=hidden name=item VALUE="%cartID%">

<INPUT type=image border=0 name=checkout src="http://yourdomain//gl-out.gif" width=154 height=46>

</td>

<td>

</FORM><FORM action="http://www.cartserver.com/sc/cart.cgi" method=POST>

</td>

<td>

<INPUT TYPE=hidden name=item VALUE="%cartID%">

<INPUT type=image border=0 name=view
src="http://yourdomain//gl-view.gif" width=154 height=46>

</TD>

</td>

<td>

</FORM>

</td>

</tr>

</table>

</body>

</html>

Referencing HTML page

The referencing HTML page contains HTML coding which will invoke CatalogMgr.pl.

<html>

<head>

<title>Sample Online Catalog</title>

</head>

<body>

<p align="center"><big><big><font color="#FF0000"><big><big>Sample Online Catalog</big></big></font></big></big></p>

<p align="center">Shop and save from the comfort of your own PC</p>

<!—invoke CatalogMgr with an href -->

<a href="http://yourdomain/cgi-bin/VirtualCatalog/CatalogMgr.pl?
cartID=yourID&SearchField=category&SearchFor=books&template=
Htx/sample1.htx&hdr=Collection+of+books&displayNumber=25">

<img src="wb01518_.gif" width="55" height="45" alt="Buy books" align="middle" border="0">Books from Our Catalog</a>
- simple presentation of catalog entries, all displayed on one page</p>

</body>

</html>

Sample Database

Data to be used with sample catalog page template. The data can be found in the file sample.cdb, and is ready for use as a sample database.
 

Part #	Description	Detail	Category	Cost	Qty	image URL
B-001	Access 97 Bible	<b>Access 97 Bible</b><br> <i>Cary N. Prague & Michael R. Irwin</i></br> ISBN: 0-7645-3035-6	Books	49.99	1	http://yourdomain//B-001.gif
B-002	HTML Publishing on the Internet	<b>HTML Publishing on the Internet</b><br> <i>Brent Heslop & Larry Budnick</i></br> ISBN: 1-56604-229-1	Books	49.95	1	http://yourdomain//B-002.gif
B-003	HTML Visual Quick Reference	<b>HTML Visual Quick Reference</b><br> <i>Dean Scharf</i></br> ISBN: 0-7897-0411-0	Books	14.99	1	http://yourdomain//B-003.gif
B-004	Web Publishing Unleashed	<b>Web Publishing Unleashed</b><br> <i>William R. Stanek</i></br> ISBN: 1-57521-272-2	Books	69.99	1	http://yourdomain//B-004.gif
B-005	Using PERL 5 for Web Programming	<b>Using PERL 5 for Web Programming</b><br> <i>David Harlan, Shelley Powers, Paul Doyle, & Micheal O Foghlu</i></br> ISBN: 0-7897-0659-8	Books	49.99	1	http://yourdomain//B-005.gif
B-006	PERL 5 Quick Reference	<b>PERL 5 Quick Reference</b><br> <i>Micheal O Foghlu</i></br> ISBN: 0-7897-0888-4	Books	19.99	1	http://yourdomain//B-006.gif
B-007	Teach Yourself PERL in 21 Days	<b>Teach Yourself PERL in 21 Days</b><br> <i>David Till</i></br> ISBN: 0-672-30586-0	Books	29.99	1	http://yourdomain//B-007.gif

Order VirtualCatalog™ Today