Integrating TclHttpd with Your Application

The bulk of this chapter describes the various ways you can extend the server and integrate it into your application. TclHttpd is interesting because, as a Tcl script, it is easy to add to your application. Suddenly your application has an interface that is accessible to Web browsers in your company's intranet or the global Internet. The Web server provides several ways you can connect it to your application:

• Static pages — As a "normal" Web server, you can serve static documents that describe your application.

• Domain handlers — You can arrange for all URL requests in a section of your Web site to be handled by your application. This is a very general interface where you interpret what the URL means and what sort of pages to return to each request. For example, http://www.tcl.tk/resource is implemented this way. The URL past /resource selects an index in a simple database, and the server returns a page describing the pages under that index.

• Application Direct URLs — This is a domain handler that maps URLs onto Tcl procedures. The form query data that is part of the HTTP GET or POST request is automatically mapped onto the parameters of the Application Direct procedure. The procedure simply computes the page as its return value. This is an elegant and efficient alternative to the CGI interface. For example, in TclHttpd, the URLs under /status report various statistics about the Web server's operation.

• Document handlers — You can define a Tcl procedure that handles all files of a particular type. For example, the server has a handler for CGI scripts, HTML files, image maps, and HTML+Tcl template files.

• HTML+Tcl Templates — These are Web pages that mix Tcl and HTML markup. The server replaces the Tcl using the subst command and returns the result. The server can cache the result in a regular HTML file to avoid the overhead of template processing on future requests. Templates are a great way to maintain the common look and feel to a family of Web pages, as well as to implement more advanced dynamic HTML features like self-checking forms.

TclHttpd Architecture

You may find it helpful to read the code to learn more about the features of the server. In this section, there are references to Tcl files in the source, which are in the lib directory of the distribution that is on the CD-ROM.

Figure 18-1 shows the basic components of the server. At the core is the Httpd module (httpd.tcl), which implements the server side of the HTTP protocol. The "d" in Httpd stands for daemon, which is the name given to system servers on UNIX. This module manages network requests, dispatches them to the Url module, and provides routines used to return the results to requests.

The Url module (url.tcl) divides the Web site into domains, which are subtrees of the URL hierarchy provided by the server. The idea is that different domains may have completely different implementations. For example, the Document domain (doc.tcl) maps its URLs into files and directories on your hard disk, while the Application Direct domain (direct.tcl) maps URLs into Tcl procedure calls within your application. The CGI domain (cgi.tcl) maps URLs onto other programs that compute Web pages.

Adding Code to TclHttpd

The TclHttpd distribution, which is described in more detail starting at page 284, is set up so you can easily add code for your application into the server. For simple applications, you simply put your files into a special directory for custom code, and the server loads them automatically upon startup. These files should define Tcl procedures and register them as Domain Handlers, Direct URL handlers, or Document handlers. Example 18-1 implements /hello/world:

Example 18-1 The hello.tcl file implements /hello/world

Direct_Url /hello Hello
proc Hello/world {} {
   return "<b>Hello, World!</b>"
}

Suppose you put that file into the directory /tmp/tclhttpd_test. Then you can start the server like this:

tclsh8.3 bin/httpd.tcl -library /tmp/tclhttpd_test -debug 1

Now access this URL:

http://localhost:8015/hello/world

Custom Main Programs

The TclHttpd main program, bin/httpd.tcl, may conflict with the main program of your existing application. For those applications that embed Tcl interpreters in a more custom manner, you will need to modify bin/httpd.tcl for use with your application. That script is not very big, and it is well-commented. The key elements are the Httpd_Server call that opens the listening socket for the Web server, and the vwait at the very end that activates the event loop. The rest is all about argument parsing and initializing the various modules that support the server. It is those aspects that may differ for your custom server application.