PowerWeb Commands

Table of Contents

Introduction
PowerWeb Command Reference $Imagemap Invokes the built-in image mapping server.
$Form Invokes the built-in form processing facilities.
$Wizard Creates new HTML documents using Wizards, templates and styles.

The PowerWeb Commands act like a normal URL, but are mapped to internal built-in commands within the PowerWeb Server, bypassing the overheads and complications of CGI programming.

This performance advantage is particularly significant for imagemap processing, where the overhead on other vendor's servers of loading the imagemap program is typically 80% of the workload. PowerWeb's low overhead ensures that adding clickable images to your pages doesn't bring your server to its knees.

The /$ImageMap command provides the full functionality of an image map processor, including support for the polygon, circle, rectangle, nearest point and default sub-commands within the image map configuration file.

The /$ImageMap command is fully compatible with existing image map processing programs, and the format of its configuration files is also fully compatible with servers such as NCSA, making it a true drop-in replacement.

When PowerWeb configures itself automatically on installation, it defines an Alias which maps your existing /cgi-bin/imagemap programs to the built-in /$imagemap. You don't need to do anything to your existing documents to take advantage of PowerWeb's built-in imagemap support.

The Guided Tour has a complete example of /$ImageMap in action.

Process forms automatically with PowerWeb's parameter-driven forms handling. In conjunction with PowerWeb Macros, you can manipulate and process multi-page forms without resorting to CGI scripts.

To invoke the automatic form processor, use /$Form as the action for your form tag in your HTML document.

For example:

<Form Action="/$Form" Method=POST>

The /$Form command requires some parameter fields to be contained within your form so that these are submitted along with the rest of the form data. These parameters are coded as hidden fields within your document.

For example:

<Input type=hidden name=form_fields value="config:/Version,*">

form_file
Specifies the file in which to save the form data. The data is stored in comma-separated-variable format. Those fields specified by the attribute "form_fields" are stored. If "form_format" is "arglist", then the data is stored in the same format as an HTTP form request where each data item is stored as "name=value" and separated by ampersands. The "form_file" attribute is ignored if "form_url" is specified.

The "form_file" file is appended to as each /$form command is received. It is fully multi-thread safe, performing file locking to ensure no conflict when multiple requests are received simultaneously. To access the form fields for the current request, use the variables contained in the "Request:/Arguments" variable directory.

The URL within form_file, is not allowed to be relative to the current document, so you must always specify a full URL.Example: "/tour/database/pizza.csv"

form_url
Specifies the URL (local or external) to which the form data should be forwarded.

The form processor performs the "form_before" and "form_check" checks prior to sending the data to the specified URL. In addition, only those fields specified within "form_fields" are forwarded.

The main purpose of using a URL is to act as a forwarding agent to another server, while optionally performing timestamping, validation and logging on the server where the form was submitted.

This attribute should be used in conjunction with "form_format" and "form_fields".

Example:

<Input type=hidden name=form_url value="http://www.compusource.co.za/powerweb/orders.htm">

form_mail
Specifies the mail id to which the form data should be mailed. By default, PowerWeb will use the SMTP server running on the same machine in order to deliver the mail.

If you need to deliver mail via a gateway or a different machine to that which PowerWeb is running on, use the syntax: @gateway:user@host

Example 1: stats@research.com
Example 2: @mail-relay.acme.com:stats@research.com
Example 3: @smtp.acme.com:stats@acme.com

The comments under "form_url" regarding "form_before", "form_after" and which fields are submitted, apply also to "form_mail".

form_fail
Specifies the local URL or the HTML text to display if an error is encountered while submitting the form by mail or by proxy to a URL.

form_fields
Specifies the list of fields to store or to forward. Each field name should be separated by a comma. The special field name '*' outputs all fields. By default, if no form_fields parameter is given, all fields are output.

form_format
The format for storing the fields is by default Comma-Separated-Variable (CSV). The alternative formats are "arglist" (the HTTP method of encoding fields and their values) and "stf" (the Lotus Notes method of encoding fields and their values).

If you are using the form_url sub-command to forward the form data, you should specify "form_format=arglist", so that the recipient HTTP server will be able to understand the data.

If no form_format parameter is given, comma-separated-variable format is used.

Example:

<Input type=hidden name=form_format value=arglist>

form_check
Defines a local virtual URL of a PowerWeb Macro document that performs field validation. The PowerWeb Macro document is expected to create and set the variable "form_valid" to 1 or 0 accordingly. If the form contents are invalid (form_valid is 0), the PowerWeb Macro can output its own error messages to be sent to the client, in which case the form data is not stored on the server. If "form_valid" is set to 0, but the PowerWeb Macro document output no text, then a default server-generated error message is returned to the client.

Example of setting the "form_valid" variable with a Web Macro:

<!--#if empty=product -->
<h2>You did not fill in all the fields correctly</h2>
<b>Please go back and fill them in correctly.</b>
<!--#create name=form_valid type=integer value=0 -->
<!--#else -->
<!--#create name=form_valid type=integer value=1 -->
<!--#endif -->

form_ok
Defines a message or local URL to display to the client upon acceptance of valid form data.

form_before
Specifies an API hook to call to perform pre-processing of the form data. Internal attributes within the parameter value define which function to call. The "form_before" hook is called prior to the "form_check" document being called.

The Attributes Are:

Exec
This must be "api", "perl" or "rexx".

Module
If the "exec" is "api", this is the name of the dynamic library which contains the API Hook Function to call. If the library is in the PowerWeb Server bin directory, you do not need to specify a path or an extension. For a "rexx" interface, this attribute is the name of the command file.

Function
The name of the function to call within the specified module. The function must comply with the PowerWeb API Hook interface specification.

Example:

<Input type=hidden name=form_before value="exec=api module=forms function=before">

form_after
Specifies an API hook to call to perform post-processing of the form data after it has been stored. Internal attributes within the parameter value define which function to call, just like for the "form_before" parameter.

<Form Action="/$form" Method=POST>

<Input type=hidden name=form_file value=/example/rexxform.frm>
<Input type=hidden name=form_fields value="connect:/RemoteAddress,*">
<Input type=hidden name=form_before value="exec=rexx module=/example/rexxform.cmd">

Your name: <Input type=text name=name>

<Input type=submit value="Submit">

</Form>

This would call the Rexx module /example/rexxform.cmd to perform any pre-processing required before storing the data set in the file /example/rexxform.frm, which would have as its first field the IP address of the remote client who submitted the form.

The Guided Tour has a complete example of /$Form in action. It also shows how PowerWeb Server++ API extensions can be used to view the resulting database files.

The /$Wizard command is used in conjunction with PowerWeb Macros to automatically generate new HTML documents based on templates.

The user executing the /$Wizard command must have permission to execute protocol "HTTP" with the "PUT" method for the resource specified in the "virtual_destination".

template
Specifies the local URL which contains the template document.

destination
Specifies the local URL in which the generated document should be stored.

The main Administration page has a complete example of /$Wizard in action to create a customised home page for a server.