Wapp

Artifact [0a0eacca36]
Login

Artifact 0a0eacca365f5630fffc0bae8b34107bbce71c2af8ce1b0b9dd52ba4bc2d340b:


Wapp - A Web-Application Framework for TCL

1.0 Introduction

Wapp is a simple and lightweight framework that strives to simplify the construction of web application written in TCL. The same Wapp application can be launched in multiple ways:

All four methods of launching the application provide the same interface to the user.

1.0 Hello World!

Wapp is designed to be easy to use. A hello-world program is as follows:

package require wapp
proc wapp-default {} {
   wapp "<h1>Hello, World!</h1>\n"
}
wapp-start $::argv

The application defines one or more procedures that accept HTTP requests. For an HTTP request where the initial portion of the URI is "abcde", the procedure named "wapp-page-abcde" will be invoked to construct the reply. If no such procedure exists, "wapp-default" is invoked instead.

The procedure generates a reply using one or more calls to the "wapp" command. Each "wapp" command appends new text to the reply.

The "wapp-start" command starts up the built-in web server.

To run this application, but the code above into a file named "main.tcl" and then run type "tclsh main.tcl" at the command-line. That should cause the "Hello, World!" page to appear in your web browser.

1.1 A Slightly Longer Example

Information about each HTTP request is encoded in the global ::wapp() array variable. The following sample program shows the information available in ::wapp().

package require wapp
proc wapp-default {} {
  global wapp
  wapp "<h1>Hello, World!</h1>\n"
  wapp-unsafe "<p>See the <a href='$wapp(BASE_URL)/env'>Wapp "
  wapp "Environment</a></p>"
}
proc wapp-page-env {} {
  wapp "<h1>Wapp Environment</h1>\n"
  wapp "<p><ul>\n"
  foreach var [lsort [array names ::wapp]] {
    wapp <li>
    wapp-escape-html "wapp($name) = $::wapp($name)\n"
  }
  wapp "</ul></p>"
}
wapp-start $::argv

In this application, the default "Hello, World!" page has been extended with a hyperlink to the /env page. The "wapp-unsafe" command works exactly the same as "wapp" (it appends its argument text to the web page under construction) except that the argument to "wapp-unsafe" is allowed to contain TCL variable and command expansions. The "wapp" command will generate a warning if its argument contains TCL variable or command expansions, as a defense against accidental XSS vulnerabilities.

The /env page is implemented by the "wapp-page-env" proc. This proc generates an HTML unordered list where each element of the list describes a single value in the global ::wapp() array. The "wapp-escape-html" command is like "wapp" and "wapp-unsafe" except that "wapp-escape-html" escapes HTML markup so that it displays correctly in the output.

1.2 The ::wapp() Global Variable

To better understand how the ::wapp() array works, try running the previous sample program, but extend the /env URL with extra path elements and query parameters. For example: [http://localhost:8080/env/longer/path?q1=5&title=hello+world%21]

Notice how the query parameters in the input URL are decoded and become elements of the ::wapp() array. The same thing occurs with POST parameters and cookies - they are all converted into entries in the ::wapp() array variable so that the parameters are easily accessible to page generation procedures.

The ::wapp() variable contains additional information about the request, roughly corresponding to CGI environment variables. To prevent environment information from overlapping and overwriting query parameters, all the environment information uses upper-case names and all query parameters are required to be lower case. If an input URL contains an upper-case query parameter (or POST parameter or cookie), that parameter is silently omitted from the ::wapp() variable

The ::wapp() variable contains the following environment values:

1.3 Additional Wapp Commands

The following utility commands are available for use by applications built on Wapp:

1.4 Design Rules

All global procs and variables used by Wapp begin with the four character prefix "wapp". Procs and variable intended for internal use begin with the seven character prefix "wappInt".