Overview

Overview of Web Server Plug-ins

A web server plug-in extends the functionality of the web server. Essentially, when a web server is launched, it looks to determine whether any plug-ins are installed. If plug-ins are found, they are loaded, so that the web server becomes aware of the new types of requests that can be handled, and which plug-in should receive the request.

Overview of PortWeb

PortWeb works by registering itself with the web server, so that the web server knows to pass certain types of requests on to PortWeb.

The general process that occurs in a user’s search through PortWeb is as follows:

1. The user loads a static HTML search page containing a search form.

2. The user enters search criteria and submits the form.

3. The web server passes the form data over to PortWeb.

4. PortWeb parses the data and performs the search in a specified Portfolio catalog.

5. PortWeb parses the specified Export HTML template.

6. PortWeb merges the search results with the template and returns the page back to the user’s web browser (via the web server) for display.

    

Plug-In Communication Methods

In general, there are two mechanisms for communicating with a web server plug-in. These are known as the GET and POST methods.

Note that the GET method can be used in a form (simply by setting the Method to “GET”), but it is common practice to use the POST method in these situations.

The primary difference between the two methods is that POST allows for user intervention via a form for changing parameters, while the GET method has hard-coded parameters. Each of these methods is useful, depending on the situation. For example, if you wanted to have a simple button that automatically searches a particular catalog for a particular keyword, then the GET method is the simpler and more concise approach. However, if you’d like to ask the user for particular parameters (such as the keywords to search for) then a form using the POST method is more applicable. In addition, the POST method can have unlimited request data and parameters, but the GET method can be limited to 4K of request information (depending on the browser).

PortWeb fully supports both methods, and there are actually situations where it makes sense to use both methods on the same HTML page.

PortWeb Request Types

Regardless of which method is used to communicate with PortWeb, the general structure of the request is the same. Each time a request is sent to the plug-in, the web server must first identify the plug-in, then the plug-in identifies the command to be executed and the parameters necessary for that command to work.

Identifying the Plug-In

The plug-in’s location must always be provided in a request. This is what tells the web server to pass the request on to PortWeb. Plug-ins are identified differently on different platforms. Refer to the section corresponding to the platform of your web server. Throughout this section, the two platforms will be used interchangeably. Be sure to use the syntax appropriate for your platform, as shown in the tables.

Windows

In both cases (GET and POST), you must provide not only the name of the plug-in, but also the path to the plug-in on the server. The simplest mechanism for referencing the plug-in is to use a “root-relative” path, such as “/scripts/PortWeb.dll...” This indicates that the plug-in is located in the “scripts” directory at the root level of the web server.

Alternately, you could use a full URL to locate the plug-in, such as:

This is often used when the plug-in is running on a web server other than the one serving the web pages.

Macintosh

Normally, the path to the plug-in is not required. This is because the plug-in is registered with the server when the web server launches. However, if the plug-in is on a separate web server other than the one serving the web pages, you would use the full URL.

For example:

PortWeb Commands

The commands currently supported in PortWeb are shown in the table below.

Tip: For sample templates and more details about PortWeb HTML, see PortWeb Templates.

The command is always passed in immediately following the plug-in location. The question mark (?) is used to indicate the beginning of the request variables. The first variable indicates which request (quickfind, query, etc.) to perform.

Using the GET method, the command immediately follows the plug-in location.

Using the POST method, the command is identified in the second half of the ACTION attribute:

PortWeb Parameters

Each command requires one or more parameters. These are all the variables that affect what the command does. For example, two of the most important parameters for any request are the name of the catalog to search and the response template to be used.

Using the GET method, parameters are specified directly within the HREF, and are entered as value pairs (a parameter and its value). Each value pair is separated by an ampersand (&). The parameter is separated from the its value by an equals sign (=). In the following example, the parameter “catalog” is passed in with the value “Sample.”

Using the POST method, the parameters are defined using form INPUT tags. In the following example, the parameter “catalog” is passed in with the value “Sample.” In this case, the parameter is hidden, so that it cannot be modified by the user. Other INPUT types (such as “TEXT”) could be used to get information from the user. For more information on setting up HTML forms, please refer to an HTML reference guide. (See Required Knowledge for suggested starting points).