[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13. CGI introduction

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] [ ? ]

13.1 Diagram

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] [ ? ]

13.2 Notation

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] [ ? ]

13.3 Style parameter

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] [ ? ]

13.4 Database table parameters

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>
Simple case
<input type=text name=url size=20>
Table name specified
<input type=text name=company_name size=20>
<input type=text name=customer_name size=20>
Alternate value within a list
<select name=provider>
<option value=hrnet>HRNet
<option value=eunet>EUNET
</form>
<input type=text name=provider_alt size=20>

Here is the generic form of parameter names for database records.

`fieldname'
`table_fieldname'
`fieldname_alt'
`table_fieldname_alt'


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.5 Primary parameter

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] [ ? ]

13.6 Recursive CGI call

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] [ ? ]

13.7 CGI called with PATH_INFO

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] [ ? ]

13.8 Multipage results parameters

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.

`page_length (default 10)'
`page (default 1)'

The associated template part is described elsewhere, See section Multipage results template.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by root on October, 27 2004 using texi2html