URL Domains

23:32 PM Learn | Basic Setup | Templates | Server Security | Direct URLs | URL Domains

A URL domain handler is responsible for all aspects of URL processing, except for Server Security checks. The domain handler has to interpret the URL, the query data, and generate a response to the client. The Document Domain and its Templates scheme is an example of a URL domain that handles many of these details automatically for you. The Application Direct URL domain is another example that handles the details. In this page we give you a quick introduction to what you need to do to provide your own URL domain handler. You should also look at lib/direct.tcl, lib/doc.tcl, and lib/template.tcl for the implementation of these domains.


You define the URL domain with Url_PrefixInstall. The basic call defines the URL prefix and the procedure to call to handle that part of the URL namespace. For example:

Url_PrefixInstall /sample ::sample::domain
This call causes every URL that begins with "/sample" to be processed by the ::sample::domain procedure. That procedure is passed two arguments, a socket connection and the URL suffix (i.e., the rest of the URL). You can specify additional features of your domain: see the URL man page for details.

Sample Domain Handler

Here is a sample domain handler.
Url_PrefixInstall /sample ::sample::domain

proc ::sample::domain {sock suffix} {

   # Ensure pathname is OK, and figure out if
   # there is a trailing slash in the URL.  This can
   # be important when generating relative URLs in the result.

   set components [Url_PathCheck [string trimleft $suffix /]]
   if {![regexp {.*(/)$} $suffix _ slash]} {
     set slash ""

   # Set up ncgi environment for access to query data

   Url_QuerySetup $sock

   # Now look at suffix, or components, and decide what to do
   # Here we just look at the first URL component after the
   # prefix and show a few typical actions

   switch -- [lindex $compoments 0] {
     "test" {
       Httpd_ReturnData $sock text/html "Hello, World!"
     "motd" {
       # Return the Message of the Day file
       if {[file exists /etc/motd]} {
         Httpd_ReturnFile $sock text/plain /etc/motd
       } else {
         Doc_NotFound $sock
     "home" {
       # Redirect to a different URL, in this case the home page
       Redirect_Self /
     default {
       Doc_NotFound $sock
HomeStatusLearnCGI TestsTemplatesAccess ControlReference Manual