MaxiVend Reference

Version

This document describes MaxiVend 1.3.11, written by Mike Heins.


DESCRIPTION

MaxiVend is a CGI-based user interface for MiniVend, the powerful freeware shopping cart. It gives a user interface suitable for catalog control and operation without need for telnet interaction by the user.


A bit about MiniVend

MiniVend allows customers to select items to buy from catalog pages. The program tracks which products they have selected and the quantity desired. From the ordering page they may complete the ordering process by entering their name and address, or return to browsing and select more items. Once the order process is completed, MiniVend submits the order to the system via email or an external order entry program.

Though its name begins with ``Mini'', MiniVend is anything but. It is a high-end, fully customizable, powerful software system with complete database functionality. It is suitable for many applications besides shopping carts, though that is its main bent.

MiniVend plugs into a system with an SSL (Secure Sockets Layer) server, allowing encrypted transmission of sensitive customer data. This capability makes the entry of credit card numbers practical and secure.

Many different catalogs can be run from the same MiniVend server, allowing an ISP to serve many different customers from one or just a few MiniVend server processes. As many as 800 MiniVend catalogs have been run on one machine from the same server process.

Multiple servers can be forked to serve the same set of catalogs. This ensures fast response, while only one server runs when there is no catalog activity.

MiniVend is powerful, and correspondingly complex. It can easily handle catalogs of a million items or more, with excellent performance. It has completely flexible page display, search, and order entry capability. If you only have a few items to catalog, MiniVend is probably overkill for your needs. But if you are willing to spend some up-front learning time, it can support your simple catalog with unlimited room to grow. To get a fast start with a simple catalog, start with the simple demo and customize from there.

You can get more information on MiniVend at its web site:

        http://www.minivend.com/minivend/


Getting MaxiVend

MaxiVend is not freeware like MiniVend. It is not currently available in end-user form; it is designed to be run by an ISP or other dedicated server.

For availability, contact:

        Internet Robotics
        131 Willow Lane
        Oxford, OH 45056
        +1.513.523.7621
        sales@minivend.com


OVERVIEW OF MAXIVEND

MaxiVend is integrated into MiniVend with a series of addon Perl modules, MiniVend pages, and MiniVend user-defined tags. It uses one addon CGI program, mv_upload, which is only used for uploading new database source or pages and configuration files.

It is designed to work in concert with a good FTP program or a Samba- or NFS-mounted directory where you will edit pages (and possibly export database source) from your local machine. MaxiVend provides very little page-editing support at this time.

The configuration pages are in normal MiniVend page space, but are protected via HTTP basic authorization. If you don't wish to set up an HTTP secure CGI area, MiniVend's internal HTTP server will automatically prevent login by any except the MiniVend RemoteUser.

The interface is presented as three frames in an HTML browser. A frames-enabled and JavaScript-enabled browser is required; no Java is used. The three frames are named header, navigation, and content.

The top frame, header, is a control/status panel. It controls the server configuration, provides top-level menu selections, and displays status information.

The left frame, navigation, selects configuration parameters or database keys to display and edit. If a configuration setting, directive, or database key is selected from it output will usually go to the content frame.

The large frame, content, is where editing occurs; occasionally complex menus like database configuration will be displayed there.

Configuration directives (the contents of a MiniVend catalog.cfg file) are edited in a working configuration. The working configuration does not take effect until the catalog is reconfigured, which can be done in the header frame by clicking the Reconfigure link. Reconfiguration will normally take effect within seconds.

The working configuration then becomes the running configuration.

The previous running configuration is saved (if there were any changes made), and if a mistake is made, you may Unconfigure, which will send you back to the previous configuration (known as the saved configuration.

Database editing is done by first selecting a table, which is a normal MiniVend database table.

IMPORTANT NOTE: All edits and changes are made on the actual database; the ASCII source file does not change unless you export it.

Once a table is selected (it will default to products), then you can edit entries (or keys) in the database with several different selection and view options.

Keys can be inserted, updated, or deleted from any MiniVend table including SQL databases.

A ``spreadsheet'' mode is usable for smaller databases; for larger ones (greater than 1 megabyte) it is disabled except for a key search mode which can select only certain keys from a large database table.

You can always input a key name (product code) directly to edit the complete contents of the entry.

You can upload new ASCII database source from the configure/export/upload menu available for each table; as with configuration files, these database source files are saved as a working/running/saved, and may be rotated in and out.


THE HEADER or CONTROL/STATUS PANEL

The header panel displays the status of the working, running, and saved MiniVend configurations; it provides links to reconfigure and unconfigure the catalog; has a link for displaying the contents of the catalog error log; and selects Configuration or Database functions.


Configuration Menu

This link causes the navigation panel to display MiniVend directives for configuration. They appear in a series of grouped functions; you can switch to alphabetical display in navigation.


Edit Databases

This link drops the database selector panel into the navigation frame.


Error Log

This link causes the error log to be displayed in the large content frame.


Refresh this frame

Reloads the header panel.


Working Configuration

The top portion of the two-sectioned area has links for:

Reconfigure
Causes the MiniVend server to reread the configuration from the working catalog configuration file (catalog.cfg+) if present, and the running configuration (catalog.cfg) if it is not.

You may wonder why you would want to use this if no working configuration is present. The answer is that updates to the special variable, database, and locale database tables will not take effect until the catalog is reconfigured.

This link should be displayed in green if you have a color monitor.

view
Displays the contents of the working configuration (catalog.cfg+) file if it is present.

This link should be displayed in cyan/light blue if you have a color monitor.

Below the top area, a small display section displays the serial number of the working configuration with the date it was originally created.


Running Configuration

In the upper area, the time the catalog was last reconfigured (or the MiniVend server restarted) is displayed at the top of this section. It also has a view link to view the current catalog.cfg, or running configuration, file.

The lower portion displays the serial of the file along with the time it was originally created.


Saved Configuration

The top portion of the two-sectioned area has links for:

Unconfigure
Causes the MiniVend server to rotate back the old saved configuration in (catalog.cfg-) case there are problems with testing of a new running configuration.

If there is no saved configuration, then unconfiguration will not be performed.

This link should be displayed in red if you have a color monitor.

view
Displays the contents of the saved configuration (catalog.cfg-) file if it is present.

This link should be displayed in cyan/light blue if you have a color monitor.

Below the top area, a small display section displays the serial number of the saved configuration with the date it was originally created.


More about reconfiguration/unconfiguration

The running configuration is always contained in the file catalog.cfg file in the base catalog directory. Saved configuration files have a minus sign (-) appended, and working configuration files have a plus (+) sign appended.

This goes a bit further; an infinite number of saved and working configuration files may be present. If you create a series of working configurations, then the saved ones will have additional minus signs appended. So you will see directory listings like:

        catalog.cfg
        catalog.cfg-
        catalog.cfg--
        catalog.cfg---
        catalog.cfg----

If you did two unconfigure operations in succession, then the same listing would be:

        catalog.cfg++
        catalog.cfg+
        catalog.cfg
        catalog.cfg-
        catalog.cfg--


EDITING THE CONFIGURATION

When you select Configuration Menu from the header frame, a list of MiniVend configuration settings is displayed in the navigation frame. A few of these lead to special configuration pages; most go to a single display of a directive to edit.


Grouped display

When first displayed, the directives are displayed within function groups. The groups are:

Alphabetical
Displays all directly editable directives in alphabetical order. The special Variable, Database, UserTag, and Locale links are not present.

Localization
These are the most commonly manipulated settings, ones that will need to be changed for any catalog. They include the email address orders will be mailed to, URLs to call the catalog, variable settings, and internationalization parameters.

Database Setup
The first link, Database, leads to a special editing panel for database setup. This is equivalent to the MiniVend Database directive, but the configuration is maintained in a special database table called, appropriately enough, database. You can set the source file name, import type, continuation and import parameters, DBI DSN, SQL field types, and other information there.

The remaining links control other database configuration parameters like NoImport, ProductFiles, etc. Many users will never want to use these.

Shipping/Tax
Security/Session
Appearance
Pricing
Cart/Ordering
Static/Cache
Search
Frames
Miscellaneous
Directories
Sets the directories that MiniVend uses to contain different types of files. Don't change these settings unless you are an expert.

Compatibility
Sets functions which are deprecated from earlier versions of MiniVend. If you change the defaults from the MaxiVend supplied template, you may cause poor interaction with other functions. Use only if you are integrating an existing catalog for maintenance. Do not use for new designs.

head1 DATABASE EDITING

Maxivend allows editing, uploading, and exporting of any MiniVend database table, with a variety of views and options available. Any of the operations will operate on any attached Minivend database table except for session databases.


Accessing Database Edit

In the header frame there is a link to Edit Databases. Follow this link which will provide a panel in the navigation frame.

Some of the configuration operations -- Locale, Variable, Database, ActionMap, and SpecialPage -- are actually views into database edit.


Edit control panel

The edit control panel is the means for selecting keys (items) to edit, and provides several links to other menus.


Select new table

It shows the currently selected table, by default products. When you pull down the select box on this control you will be shown all editable databases. (There are a few that are hidden by default; they can be unhidden in MaxiVend control under the Miscellaneous configuration menu.)

This control should automatically cause a refresh of the Edit control panel and display the new table name.


Key to edit/insert

Unless you have a very large database, you will be given several options for selecting items (keys) to edit. There are:

SELECT box
You can display all of the keys in a table in a select box. By default, it is a normal dropdown; but you can disable it to speed up access, and you can select different-sized windows to show multiple keys on the list. When you select a key and press the nearby Edit button, that single record will be displayed in the large content frame and be ready for edit.

If your database is larger than 100,000 bytes in size, you will not be given this option.

TEXT box (or enter key:)
You can input a key name directly, and when you press enter (or click the nearby edit button) then that single record will be displayed in the large content frame and be ready for edit.

Spreadsheet
If you check the spreadsheet box and press the Edit button, then a spreadsheet-like view will be displayed in the large content frame.

Key search
There is a small text box in a shaded area. This will search for text in the database ASCII source file and display those keys which match the search text. If you wish to do extended searching, then there is a link to the extended Key Search functionality.


Decode HTML entities

If you wish to enter extended characters you can set Decode HTML entities to yes. EXPAND


Configure/export/upload

This sends a database control menu to the large content frame.


Limit fields to display

This area is a series of checkboxes which select individual columns/fields that can be displayed when the Edit key is pressed. This might be helpful when your database has many columns and you wish to select a subset of columns to view in edit or spreadsheet mode.

To use this feature, check the boxes corresponding to the names of fields you wish to edit/view, and click the Limit button. To reset to the default of all fields displayed, click the ALL button.


CONFIGURING, EXPORTING, AND UPLOADING DATABASE TABLES

MiniVend stores data in any number of formats. By default, it uses a GDBM or DB_File DBM-based format (if available). It can also use any of many SQL-based databases (Oracle, Informix, MySQL, Sybase, MS-SQL, and mSQL are just a few examples). Or if none of the above are available, it will store a database in memory; that is pretty volatile, for the moment you stop the MiniVend server it will lose any updates you have made to a database table.

To load these databases, MiniVend can automatically import from any of 6 different ASCII file formats:

TAB
Typical header record and first record of a table's ASCII source:

  code     description   image     price
  00-0011  Mona Lisa print   mona.jpg   100.00

This is MiniVend's preferred and default format. TAB delimits fields, newline delimits records.

The field names are always on the first line of the file. It is recommended you use all lower case or all upper case to prevent capitalization errors; MiniVend is case sensitive.

MiniVend prefers this format because it makes it easy to search ASCII files and return their contents. If you keep your files in some other format like CSV, you might consider exporting an ASCII version just for searching.

No quotes are necessary (nor desirable) around fields; if you produce files with Microsoft's Excel, which has a longstanding bug whereby they surround TAB-delimited fields with quotes when they contain a quote (or comma), then use MiniVend's EXCEL modifier to compensate.

PIPE
Besides TAB, this works best for MiniVend. A vertical bar (|), or PIPE symbol, is used to delimit fields while newline delimits records.

Typical header record and first record of a table's ASCII source:

  code|description|image|price
  00-0011|Mona Lisa|print|mona.jpg|100.00

CSV
This is probably the format that allows the most reliable exchange between different database programs. MiniVend imports this format just fine, but will have difficulty searching the ASCII source file.

Commas delimit fields, and newline delimits records. If a comma is within a field it must be surrounded by double quotes; if a double-quote is within a field it should be paired with another double quote.

Typical header record and first record of a table's ASCII source:

  code,description,image,price,height,width
  00-0011,"Mona Lisa, lightswitch cover",mona.jpg,100.00,5"",3""

LINE
Each field is on a line by itself. A blank line terminates a record. This format is best when used in conjunction with NOTES, described below.

Typical header record and first record of a table's ASCII source:

        code
        description
        image
        price
        height
        width
 
        00-0011
        Mona Lisa, lightswitch cover
        mona.jpg
        100.00
        5"
        3"

%%
Each field is delimited by a %% on a line by itself; records are delimited by %%% on a line by itself.

Typical header record and first record of a table's ASCII source:

        code
        %%
        description
        %%
        image
        %%
        price
        %%%
        00-0011
        %%
        Mona Lisa, lightswitch cover
        %%
        mona.jpg
        %%
        100.00

This format allows fields of unlimited size to be edited easily, and is suitable for containing large text descriptions.

NOTES
This is a subset of LINE mode, and is set by using that along with the NOTES modifier. It is similar to Lotus Notes structured text export format.

The header record contains the field names that will be used, along with an unnamed field called notes_field. The key or code is always the first field named in the header, and is required in each record.

Fields are specified by their field name and a : (colon), followed by the contents of the field. Order is not important, and not all fields must be present in a record. (Of course the key must always be there if you are to access the record.)

The special notes_field begins at the first blank line in a record, and continues until the record separator.

Records are delimited by a form feed (CONTROL-L) on a line by itself.

This format allows free-form editing of a database record with a text editor without a rigid and error-prone format.

Typical header record and first record of a table's ASCII source:

        code
        image
        price
  
        code: 00-0011
        price: 100.00

        Here is the contents of the notes_field,
        accessible with [data table notes_field key] or
        [item-data table notes_field], etc. It ends at the
        record separator (^L) below.
        ^L

There are other possible format options for the NOTES mode; here we describe the default case. See the MiniVend documentation for more information.

The database configuration itself is contained in a database table named database. It is accessed by following the <B>Database</B> link on the configuration menu page (grouped by function).

Each database has a file selection attribute, a format (TAB, CSV, PIPE, etc.) and several other parameters like EXCEL, CONTINUE, and MEMORY. See the MiniVend documentation for their use.

The Configure/export/upload menu can be reached by following a link in the database edit selector; remember that is in the navigation (left) frame. When that link is followed a menu will be displayed in the large content frame.


Export

The Export function allows you to export a MiniVend table to any of its supported formats, and to any file. This is necessary if you wish to save a text copy of what is in the database.

Export as type
Selects any of the standard MiniVend types for export. NOTES format will not be usable unless the table is already specified as NOTES format.

Export to file
The name of a file to export to. The minivend user ID must have permission to write it (or the directory it will be created in). If you don't specify an absolute path, the file will be in the products directory.

If you don't enter a file name or format, the database table will be exported to the default ASCII source file; i.e. products would be exported to products.txt in the products directory.


Upload new database text source file

When you update your product line with new products, or just want to make some changes to existing products, you will often want to upload a new database.

You can FTP up your new database, but that can cause a couple of problems:

Temporarily corrupted data
While you are uploading the new database, someone may access the site. If you are writing the ASCII source file then MiniVend will attempt to build a new DBM database -- because FTP uploads don't lock a file. (This problem can also be prevented by setting IMPORT_ONCE.)

Searches on the transitional ASCII file will also produce incorrect results. And if you lose your connection in the middle of the upload, the problem could persist for quite some time.

No backup copy saved
Unless you do a RENAME or copy to a backup file, the new database will overwrite the old.

The solution is to use the Upload new database text source file option to upload a file. The upload is done to a temporary file, and then when you select the Restore or use new database text source file option the new one will be put in place. If you find that the database is incorrect, you can return to your old one at the click of a button.


EXAMPLES OF COMMON TASKS

Following is the click-by-click for several common tasks in maintaining or setting up a MiniVend catalog.


Upload new products database

  1. Header frame Access Maxivend, click (link) Edit databases.

  2. Navigation (left) frame (Dropdown menu) Select new table --> products

  3. Navigation (left) frame (Link) --> Configure/upload/export

  4. Content (large) frame (Link) --> Upload new database text source file. Input file name or use the Browse button to select a file on your local computer.

  5. Content (large) frame (Submit button) --> Upload new products.txt. Wait for upload to complete; you should now see a button Rotate in new database in the area above.

  6. Content (large) frame (Submit button) --> Rotate in new database.


Change a price in a small database

  1. Header frame

    Access Maxivend, click (link) Edit databases.

  2. Navigation (left) frame

    (Dropdown menu) Select new table --> products

  3. Navigation (left) frame

    Key to edit/insert (checkbox) --> Spreadsheet.

    (Submit button) --> Edit.

  4. Content (large) frame

    Spreadsheet for products

    Find entry you are looking for; you may have to page through to find it. Either edit the price directly and press the submit button, or access the link for the key and edit it in its own screen.

    Change a price in a large database

    1. Header frame

      Access Maxivend, click (link) Edit databases.

    2. Navigation (left) frame

      (Dropdown menu) Select new table --> products

    3. Navigation (left) frame

      (link) --> Key Search.

    4. Content (large) frame

      Export the key search file if it is not current.

      Enter search criteria to help you find the product in the text box and click the Spreadsheet search button.

      Find entry you are looking for; you may have to page through to find it. Either edit the price directly and press the submit button, or access the link for the key and edit it in its own screen.