Request Handlers

TeleFinder's Web Server has built-in handlers to support several specialized request handling methods. You can also define external handlers so that external scripting or Plug-In/CGI programs can process specific page requests.

 

Built-in Handlers

TeleFinder's built-in handers are describe below. The association between these handlers and specific file types can be modifired in the Handlers pane.

Handler	File Types
Default	.HTML .GIF .PDF
This is the "Normal" way to send HTML and graphics files. Sends HTTP responses, headers and the file's data. This method responds to "If-Modified-Since" and "Byte Serving" requests, and will be cached. Any file not handled by another handler is served by this method.

Server Parsed	.spm, .spml
Parses an HTML file and translates embedded server side include commands into HTML for the browser. The file data may be cached by TeleFinder, but the embedded commands and HTML will be processed for each request.

As is	asi, .asis
Only sends the file data. This data must contain correctly formatted HTTP response, headers and data. The file data may be cached.

ACGI	.cgi, .acgi
Converts the request into an AppleEvent that is processed by another program conforming to the Macintosh "Common Gateway Interface" (CGI) specification.

Binhex	.sit, .sea, .cpt
On the fly conversion of file to Binhex (.hqx) format. Used for downloading Macintosh files. The file's data will not be cached since it is generated at the time of the request.

Topic	BBXF
Processes the request using the "Topic.spml" template file. This lets you publish TeleFinder Message Topics on the Internet. The file's data will not be cached since it is generated at the time of the request.

 

User Defined Handlers

User Defined Request Handlers direct TeleFinder to process a request using any available handler ( built-in, plug-in or external). This lets you use CGI programs that need to handle all requests for a specific file type.

By default the list includes mappings for TeleFinder's built-in handlers. In addition, mappings registered by Plug-ins show up in this list, but cannot be modified. However, you can add additional mappings for a Plug-in.

 

Adding a New File Type

Select the "Server Settings" command from the Web menu to open the Web Settings dialog. The click on the "Handlers" icon to display the Handlers pane.

 

Then click in the "Add" button to open the Handler dialog.

Use this dialog to select the Handling method from the pop-up menu. The handler can be mapped using either a file extension ( ie: ".html" ) or Macintosh File Type ( ie: 'BBXF' ). For most files it is preferable to map using file extension since you can easily change that by simply renaming the file.

Either manually enter the extension or type, or click in the "Same As" button to let the program match one to a specific file.

After you're done, click in the OK button to add the Handler to the list.

 

Installing a User Defined Handler

This example demonstrates adding an External Handler so that your server can process requests with Frontier scripts.

Select the "Server Settings" command from the Web menu to open the Web Settings dialog. Then click on the "Handlers" icon to display the Handlers pane. Then click in the "Add" button to open the Handler dialog.

Use the Handler dialog to select "Other" from the pop-up menu. This will cause the "Name" field to appear. Enter "FRONTIER" into the name field. Then enter ".fcgi" into the Extension field. (note: .fcgi is the extension customarily used to identify Frontier scripts.)

Then click in the OK button to add the Frontier handler to the Handlers list.

You also need to create an External Handler reference to Frontier before the server will actually process Frontier scripts.

 

 

External Handlers

You can configure TeleFinder to hand-off specific page requests to external Common Gateway Interface (CGI) programs. Rather than sending the page data directly, TeleFinder sends the CGI AppleEvent to the CGI program. The CGI processes the request. TeleFinder then sends the results from the CGI to the browser. This method is necessary to serve scripts from UserLand's Frontier object database.

There are two parts to setting up an external handler:

 

Create a CGI to Handler Name Association

Using the External Handlers pane to create an association between the CGI program ( in the following example we'll use Frontier ), and a Handler Name. You can use any Handler Name you'd like, as long as it does not conflict with one of TeleFinder's built-in methods.

Select the "Server Settings" command from the Web menu to open the Web Settings dialog. The click on the "External Handlers" icon to display the External Handlers pane.

Note that Plug-ins register themselves as an external handler when they are loaded.

Click in the "Add" button to open the "External Handler" dialog.

Enter the Handler name "FRONTIER" and set the path to the Frontier application using the browse button to the right of the path text field. Click in OK to save the new handler entry.

 

Mapping the Handler Name to a File Type

Once you have created an association between the CGI and Handler Name, you need to map the Handler Name to one or more file types. The Request Handlers section describes how to do this.

 

Pre and Post Processors

Plug-ins may be selected to perform their "Pre" and "Post" processing actions. Only specific plug-ins will function properly in this mode, consult the Plug-In documentation to see if this option should be selected for it.

 

 

Plug-ins and CGI Gateways

You can extend the functionality of TeleFinder's Web Server through an external program (CGI) or internal ( Plug-In) Gateway. These programs take HTTP requests and transform them into database searches, graphical counters and a wide variety of other services.

In both cases the Web Server hands off processing of the request to the program where it is processed, the results are returned as HTML data by TeleFinder. Plug-ins are more efficient since they run "in-process," effectively as an extension to the TeleFinder application.

 

CGI Compatibility

TeleFinder and CGI's communicate using a specific AppleEvent ( WWW Search Doc ) and reply. Interested programmers can get more details on this AppleEvent from the TeleFinder developer's kit.

TeleFinder is compatible with all the MacHTTP/WebStar standard CGI programs using the WWW AppleEvent. CGI file types need to be registered in TeleFinder's Handlers list with the Handler method of "ACGI." Most CGI's are identified by the ".cgi" or ".acgi" file extension, these are defined in TeleFinder by default.

 

Plug-Ins

Plug-ins register themselves when TeleFinder loads them. So there is often no setup other than copying the Plug-In software into TeleFinder's Plug-Ins folder and resetting the server. Some plug-ins require additional data files in specific locations. The plug-in documentation should define the location of these files.

TeleFinder conforms to the WSAPI 1.2 specification, as well as the MOSAPI 1.0 Web Server plug-in spec. WSAPI is the WebStar compatible plug-in API.

A C++ framework is included in the TeleFinder developer's kit so that interested programmers can create their own plug-ins.

 

Using Gateways

Plug-In and CGI samples are included in the "Web Space/samples/" folder.

Each Plug-In or CGI comes with it's own set of directions for coding the HTML to use it. In the case of the Spider Island Gateways, pre-coded sample pages are included so you can try them without coding HTML.