This information applies to WebTen versions 1.0, 1.1.1, 2.0, Frontier 4.2.x and v4.2b11 of the CGI Framework (maintained by Brent Simmons). If anyone has any information about integrating WebTen with Frontier 5 or 6, please let us know.
| Information provided by: | ||
|
Clinton Hogge Industrial Images |
and |
Tenon Intersystems |
| January 17, 1998 | ||
Table of Contents...
WebTen is pre-configured for use with Frontier. For reference though:
1. Make an alias of the Frontier application, name it Frontier.acgi and place it in the main cgi-bin folder.
2. Set up the WebTen action handler and mime extension using the WebTen admin server:
Action Handler:
Action Action Handler ------ -------------- FRONTIER /cgi-bin/Frontier.acgiMime Extension:
Extension MIME Type Action --------- --------- ------ .fcgi text/html FRONTIER
Frontier 4.2.3 download page (any version of 4.2.x is OK)
CGI Framework v4.2b11
These files are available via anonymous FTP:
ftp://ftp.western.net/pub/wtfrontier.sit.bin
After downloading, unstuff the file and import the individual files into Frontier. The included README file and the change notes at the top of each script detail the changes to the Framework.
From Frontier's menubar, choose Suites:WebServer. From the new WebServer menu, do the following:
- Select Use Script-Based Trap if it's not already checked.
- Select Set Path to Server, navigate and select the WebTen *application*.
- Select Set Website Folder Path, navigate and select the WebTen *folder*.
- Select Set Server Name and set it to match what appears in WebTen's /server-status URL display (such as Apache/1.2.4.12 SSL 0.8.1 WebTen/2.0).
- Select Set Chunk Size and set it to 24 (K of data to return with a sendPartial call).
- Make sure Debugging is checked if you wish to view the CGI parameters sent to Frontier during a connection. These are kept at scratchpad.cgiparams. This feature can be very useful!
- If you wish, set up the "Auto-Save" agent to automatically save Frontier every [user.webserver.saveInterval] minutes using the Auto-Save sub-menu:
- Select Auto-Save Frontier.
- Select Use Dirty Root Flag if you want your CGIs to explicitly tell Frontier that it should save itself. The agent won't execute unless user.webserver.flDirtyRoot is set to true. Your CGIs can call webserver.setDirtyRoot () to change the flag. This is useful if you want Frontier to save itself only when a specific CGI is executed.
- Select Set Save Interval to set the number of minutes between saves.
The following model shows how Frontier fits into the HTTP client/server process....
Client requests a page from WebTen by sending a GET request similar to:
GET /samples.tellTime.fcgi HTTP/1.0
Connection: Keep-Alive
User-Agent: Mozilla/3.0 (Macintosh; I; PPC)
Host: www.western.net
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
Or in the case of a submitted HTML form:
POST /wac.newsessionid.fcgi HTTP/1.0
Referer: http://www.weldersatcost.com/
Connection: Keep-Alive
User-Agent: Mozilla/3.0 (Macintosh; I; PPC)
Host: www.weldersatcost.com
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
Content-type: application/x-www-form-urlencoded
Content-length: 28
Squid checks to see if the file is cached (if you have Squid enabled in the admin server) and serves the file if it is. Otherwise, the process continues. Note that Squid will not cache any file returned by Frontier unless the CGI includes proper HTTP cache control and validation headers. To create these headers, duplicate suites.webserver.httpheader, modify it to include the cache-related headers, and call the new script in your CGIs - local (htmltext = webserver.httpHeader2 ()).
By virtue of the action handler for the .fcgi suffix, WebTen passes the request to Frontier (/cgi-bin/Frontier.acgi) via the SDOC apple event.
Frontier "intercepts" the request by the SDOC "trap" at system.verbs.traps.WWW(Omega).sdoc
Frontier passes the request in most cases to either a script at suites.webserverScripts (the default FRONTIER action for .fcgi's) or to a user-defined action whose script is located at user.webserver.actions.
The targeted script at suites.webserverScripts or user.webserver.actions processes the CGI data, formats a valid HTTP response (located at suites.webserver.httpheader), and returns the data back to WebTen. Here's two sample HTTP responses generated by Frontier...
HTTP/1.0 200 OK
Server: Apache/1.2.4.12 SSL 0.8.1 WebTen/2.0
MIME-Version: 1.0
Content-type: text/html
HTTP/1.0 302 FOUND
Location: http://www.western.net/about.mcro
URI: http://www.western.net/about.mcro
Server: Apache/1.2.4.12 SSL 0.8.1 WebTen/2.0
*Note that for some reason, AOL's proxy servers do not understand this 302 redirect response
WebTen forwards the response back to the client.
Client sends subsequent GET requests for each "element" in the return page - images, audio files, etc.
Squid processes the request if the file is in cache. If not, the process continues.
WebTen responds to the client with an HTTP response (usually 200 OK) similar to:
HTTP/1.1 200 OK
Date: Wed, 07 Jan 1998 20:18:08 GMT
Server: Apache/1.2.4.12 SSL 0.8.1 WebTen/2.0
Last-Modified: Tue, 13 May 1997 17:10:13 GMT
ETag: "12b1-4fa4-3378a075"
Content-Length: 20388
Accept-Ranges: bytes
Connection: close
Content-Type: text/html
One of the top undocumented features of Frontier as a CGI scripting platform is its ability to embed objects into HTML documents. Unlike server side includes (SSI), a Frontier embedded macro can contain any string, text, or script object from the object database. This allows you to harness the Frontier scripting engine to insert truly dynamic data in a virtually unlimited format. For a simple example, the FTP archive above includes a "counter" macro that lets you put a counter on your web page (delimited by commas). It was modified to work with WebTen's virtual hosts. Following is how to setup WebTen to process the MACRO action. More information can be found at suites.webserver.macros.readme.
Set up the WebTen action handler and mime extension using the WebTen admin server:
Action Handler:
Action Action Handler
------ --------------
MACRO /cgi-bin/Frontier.acgi
Mime Extension:
Extension MIME Type Action
--------- --------- ------
.mcro text/html MACRO
Add macros to your html documents where you want Frontier to insert the data. For example: You came from <!--#referer-->. The current time is <!--#clock.now ()-->. You are visitor number <!--#counter(scriptName,websiteFolder)-->.
Name your files containing the macros with the .mcro extension. You can also use WebTen's Action Override feature to force any combination of folders/files to use this action. If you want this action to process your DirectoryIndex files as well (files ending with a slash "/"), you need to change the DirectoryIndex setting using WebTen admin to something like default.mcro. Remember that this directive can be applied either globally, on a per-virtual host basis, or for individual folders. For this last option, you need to hand-edit httpd.conf for each customized folder:
<DIRECTORY /usr/local/etc/httpd/WebSites/yourhost.com/folder1>
DirectoryIndex default.mcro
</DIRECTORY>
The above FTP archive contains a modified version of the WebTen glue table. All of the scripts in apps.WebTen were changed to use WebTen's Finder name (located at WebTen.appInfo.name) in the return apple events, rather than WebTen's ID (WTen). This was necessary because WebTen changes its ID to WWW(Omega) - WebSTAR's ID - on startup. This was done to accommodate those CGIs and Plugins that assumed WebSTAR was the recipient of the apple event. Many of these have the WWW(Omega) event ID built in with no possibility for modification. Because WebTen responds to WebSTAR's ID, you don't necessarily need to modify your existing CGIs to use WebTen.xxx instead of Webstar.xxx. The Webstar.xxx verbs are virtually identical to WebTen's. The only downside to using them would be if you wanted to run multiple web servers on the same machine (W* and WebTen). Using the app name under the finder instead of the ID would be necessary for scripts to distinguish between the apps. Also, future versions of WebTen and the WebTen glue might include apple events that wouldn't apply to W*.
Here are some other helpful resources for Frontier CGI authors: