Document Types

The Document domain (doc.tcl) maps URLs onto files and directories. It provides more ways to extend the server by registering different document type handlers. You can make up new types to support your application. Example 18-5 shows the pieces needed to create a handler for a fictitious document type application/myjunk that is invoked to handle files with the .junk suffix. Use the Mtype_Add procedure to register the mapping from file suffix to document type:

Example 18-5 A sample document type handler

# Register the mapping from suffix to MIME type
Mtype_Add application/myjunk .junk

# Define the document handler procedure
#  path is the name of the file on disk
#  suffix is part of the URL after the domain prefix
#  sock is the handle on the client connection

proc Doc_application/myjunk {path suffix sock} {
   upvar #0 Httpd$sock data
   # data(url) is more useful than the suffix parameter.

   # Use the contents of file $path to compute a page
   set contents [somefunc $path]

   # Determine your content type
   set type text/html

   # Return the page
   Httpd_ReturnData $sock $type $data
}

The server finds the document handler in a two-step process. First, the type of a file is determined by its suffix. The mime.types file contains a map from suffixes to MIME types such as text/html or image/gif. This map is controlled by the Mtype module in mtype.tcl. Second, the server checks for a Tcl procedure with the appropriate name:

Doc_mimetype

The matching procedure, if any, is called to handle the URL request. The procedure should use routines in the Httpd module to return data for the request. If there is no matching Doc_mimetype procedure, then the default document handler uses Httpd_ReturnFile and specifies the Content Type based on the file extension. This is the heart of the default document handler:

Httpd_ReturnFile $sock [Mtype $path] $path

As another example, the HTML+Tcl templates use the .tml suffix that is mapped to the application/x-tcl-template type. You can find the document handler Doc_application/x-tcl-template in doc.tcl. The TclHttpd distribution also includes support for files with a .snmp extension that implements a template-based Web interface to the Scotty SNMP Tcl extension.