Web page scripts

A Kawa web page script is a Kawa program that is invoked by a web server because the server received an HTTP request. The result of evaluating the top-level expressions becomes the HTTP response that the servlet sends back to the client, usually a browser.

A web page script may be as simple as:

(format "The time is <~s>." (java.util.Date))

This returns a response of consisting of a formatted string giving the current time. The string would interpreted as text/plain content: The angle brackets are regular characters, and not HTML tag markers.

The script can alternatively evaluate to XML/HTML node values, for example those created by XML literals:

#<p>Hello, <b>&(request-remote-host)</b>!</p>

In this case the response would be text/html or similar content: The angle brackets should be interpreted by the browser as HTML tag markers. The function request-remote-host is available (automatically) to web page scripts; it returns the host that made the HTTP request, which is then interpolated into the response.

Following sections will go into more details about how to write web page scripts. You can do so in any supported Kawa language, including Scheme, BRL, KRL, or XQuery.

A web server will use a URL mapping to map a request URL to a specific web page script. This can be done in a number of different ways:

For details on how to extract information from the request see HTTP requests. For details on how the response is created see Generating HTTP responses. If the response is HTML or XML, you may want to read Creating HTML nodes, or Creating XML nodes, or XML literals.

Here are some examples, starting with a simple hello.scm:

(response-content-type 'text/html) ; Optional
  "The request URL was: " (request-url))
(make-element 'p
  (let ((query (request-query-string)))
    (if query
      (values-append "The query string was: " query)
      "There was no query string.")))

This returns two <p> (paragraph) elements: One using make-element and one using the html:p constructor. Or you may prefer to use XML literals.

The same program using KRL:

<p>The request URL was: [(request-url)]</p>,
<p>[(let ((query (request-query-string)))
    (if query
      (begin ]The query string was: [query)

      ]There was no query string.[))]</p>

You can also use XQuery:

<p>The request URL was: {request-url()}</p>
<p>{let $query := request-query-string() return
    if ($query)
    then ("The query string was: ",$query)
    else "There was no query string."}</p>

The +default+ script in the doc directory is useful for reading the Kawa documentation using a browser. The script uses the jar: URL scheme to automatically extract and uncompress the pages from doc/kawa-manual.epub, which is in EPUB3 format. Read the script for usage instructions.