[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The invocation style of cgi-bin programs is to specify the kind of action to be taken using the context parameter. This parameter may be seen as the name of the function to call, the functionality to be activated. It is therefore a mandatory parameter of all the cgi-bin invocations.
Should you use the POST or GET method ? The library works with both methods. Using only POST or only GET is recommended, however, because mixing the two may have surprising results when navigator caches are used.
13.1 Diagram | ||
13.2 Notation | ||
13.3 Style parameter | ||
13.4 Database table parameters | ||
13.5 Primary parameter | ||
13.6 Recursive CGI call | ||
13.7 CGI called with PATH_INFO | ||
13.8 Multipage results parameters |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
At the beginning of each chapter describing a set of cgi-bin actions, a
diagram shows a box for each action.
It describes the dependencies between the different actions
of the cgi-bin. After each textual description of the action a list of
string is shown in parenthesis. The first string is the value of the
context parameter, the unique identifier of the action,
See section CGI introduction
. Next, if appropriate,
the word recursive may appear, See section Recursive CGI call
. Finally, the name of the template used to
display the end result is shown.
In some cases, the template file match the template file name used by another action. It means that when this action completes, the action logically attached to this template is called to display the result page.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Each cgi-bin action is described in a separate section. The name of the section is followed by the unique string that identifies the action (the context parameter value).
In the description of the parameters associated with an action, the name of the parameter is followed by two strings in parenthesis. The first indicates if the parameter is mandatory or not, the second shows the default value, if optional, of the imposed value if any.
In each parameter list, the parameter name (for instance context
) may
be used in a URL in this fashion:
http://www.mymachine.com/cgi-bin/Catalog?param=1&context=value&foo=2 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All the cgi-bin accept the style parameter. It is used by the template handling library to locate the appropriate template for a given application. The template configuration file is searched for a template file map whose name equals the value of the style parameter. If no map is found, the template file name is the default file name. If a map is found but no entry exist for the default file name, the default file name is used. If an entry exists for the default file name, the file name associated with it is used in place of the default file name.
Here a portion of the template.conf file that illustrate this behavior.
style custom sqledit_search.html = custom_search.html end end |
If the value of style is custom, the results of a search
will be displayed using the custom_search.html template instead
of the sqledit_search.html template.
For a definition of the template.conf file, See section Template configuration file
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When a database record is modified or inserted, the HTML form must name the cgi-bin parameters in a consistent way so that the cgi-bin knows what was changed and modified.
The basic rule is that the parameter is named after the field name. Thus for a table containing a field named comment, when setting the value of the field to the comment, the parameter will have to be comment=the%20comment.
This convention is simple but ambiguous, if two fields of two different tables have the same name, for instance. To cope with this situation, the name of the parameter may be prefixed by the name of the table. This is always optional.
When a list of values is proposed to the user, using a menu or a set of
checkboxes, it is sometimes possible to accept a new value. For instance
if the user is prompted to select the Internet provide he uses, an additional
input box may be added to allow him to type the name of his provider, if it
is not listed. This can be achieved using a special tag, only available for
dictionaries based on tables and not on the native set
or enum
type of MySQL, See section Relational constraints
.
The name of this tag is the name of the field suffixed with _alt.
Here is an artificial example regrouping all the database parameters.
<form> |
Here is the generic form of parameter names for database records.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The cgi-bin invocations dealing with a single record will use the primary parameter to carry the unique identifier of this record in the database. If the table manipulated does not have a unique integer identifier, most cgi-bin will not work properly.
The field containing the primary key is usually named rowid and
is not type int autoincrement
. Although such a field indeed exists
for all the tables created by this library, it need not be named
rowid. The library will identify the primary key by using the
output of the show table command.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The explanation is much clearer if we begin with an example. Imagine that a cgi-bin action, named New entry in catalog, does the following:
The first two actions may be performed by an existing cgi-bin action, the
one in charge of proposing an insert form to the user and insert the
record in the database, See section Record insert form (sinsert_form)
.
When designing the New entry in catalog action, we first want
to call the Record insert form action, then perform the third
action (link record at the current point of the catalog) using
the record just created.
Simply put, a recursive CGI call occurs when a cgi-bin make use of another cgi-bin action to perform its action. From the user point of view, the action that makes use of recursive CGI is always a multi step interaction process.
The cgi-bin parameters that are visible in the URLs and are related to the recursive calls are the following:
When a cgi-bin behaves in a different way if called recursively, it will base it's action on those tags.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Assuming that you have a cgi-bin script accessed by /cgi-bin/Catalog, if you try to access /cgi-bin/Catalog/Sport/Cars/, then you call the cgi-bin with PATH_INFO instead of regular parameters. This may be very convenient if you want to give users an intuitive access to a thematic catalog. Catalog provides support for this kind of usage in the following way.
If the PATH_INFO environment variable is set when the navigation cgi-bin is called,
Catalog behaves as if called with the pathcontext context and the
pathname parameter is set with the value of PATH_INFO, See section Intuitive navigation (pathcontext)
,
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Some cgi-bin will display their result on more than one page to reduce the overhead. By default the first ten units are shown and a footer shows links that allow visualization of the following pages.
The number of units shown on a page and the page number is controlled by the following parameters.
The associated template part is described elsewhere,
See section Multipage results template
.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |