ACGI++: Quick Start

Getting Started

Introduction:

The idea behind CGI is that the client (browser) submits data to a cgi program on the web server in the form of NAME=VALUE pairs. The server actually calls the cgi script (program) with the user-submitted data. The script processes the information and, based on the input, performs some action, which typically involves the dynamic production of a new web page that is sent via the server back to the browser. The server expects to receive the cgi script output from the cgi program's stdout.

ACGI++ has been designed with two objectives:

  1. To support the CGI standard and simplify the coding necessary to comply with it.
  2. To provide developers with an object-oriented, flexible resource that can be customized and extended as needed.

This document is intended as an introduction to the library. For sake of clarity, certain advanced functions such as text-to-graphics conversion and custom font generation are not covered here. Refer to the sample applications and code comments for further information on these topics.

Conventions:

Library Organization:

The library is organized as per the acgi.gif diagram. The main classes you're likey to need are the following:

ACGI

The most commonly used class is ACGI, which contains all of the functionality for the receipt of HTTP incoming data and the output of to stdout of all response data. This class provides all the resources necessary to automatically URL-decode and parse incoming data. Since ACGI is derived from AFormList and ApairList, incoming data is stored as AElement[s] and can be retrieved by any of the calls implemented in APairList or AElementPairList.

AShoppingCart

This class, derived from APairList, is used for processing and storing shopping cart items. A shopping cart uses page-embedded information to pass data between pages and between calls to CGI scripts. AShoppingCart works in conjunction with the ACGI class. It depends on the fact that hidden page data is follows a structured naming convention:

The normal process is as follows:

  1. Instantiate an ACGI object and parse the form submission.
  2. Create a AShoppingCart object and set the shopping cart name with the ascSetName function.
  3. Pass the ACGI object into the AShoppingCart.ascFindCartItems. This creates an AShoppingCart-local copy of all name/value pairs that have the "name" contain the shopping cart name. At the same time, ascFindCartItems finds all operator submissions and performs quantity updates on the item quantity based on the operator fields.
  4. Call AShoppingCart.doOut to dump all the updated data as hidden fields to the next page you are sending to the borwser. The newly created fields follow the same naming convention, so the process can begin anew.

Note: The use of ShoppingCart Names allows for multiple concurrent shopping carts for more flexibility.

Sample code using the AShoppingCart can be found in the sample SHOPCART.cpp cgi program.

AShoppingCart will not suit everyone, but once you understand how it works, it's easy to derive your own classes that perform operations as you need them performed. For example, if your submission forms return a user-entered quantity instead of a fixed increment, you can re-design the field formats (see bullets above) and the parsing code in your AShoppingCart-derived class to handle a different scheme. You will probably have to over-ride the ascFindCartItems and doOut functions. The choice is up to you.


Other Classes and Features

There are many other classes in ACGI++. Each class is isolated to its own .h and .cpp file. Most of these are parents of the classes discussed above. Other classes, such as AXBitmap and ACrypto and AConverto are described in the main class hierarchy documentation. There are also functional examples in the SAMPLES subdirectory.