Helma Logo
main list history

Request Dispatching

Basic Use

The helma/webapp module provides a regular expression based request dispatcher. To use it, simply use the handleRequest function exported by helma/webapp as JSGI app. Since handleRequest is the default name Helma NG uses for JSGI apps it is enough to just use the module name:

exports.app = "helma/webapp";

Additionally, export a urls array in your config.js containing the dispatch rules for your application. This array may contain any number of nested arrays, each of which mapping a request path pattern to a CommonJS module (and optionally function):

exports.urls = [
    [ '/docs', 'myapp/docs', 'getDocument' ],
    [ '/', 'myapp/actions' ]
];

Each array item in urls provides a rule for handling incoming requests and consist of the following elements:

  1. The pattern. This can be a string or a regular expression. If it is a string, it is converted into a regexp. If the pattern matches the incoming request path this rule will be used to handle the request. Otherwise, the next rule in the args array is examined.

  2. The module. This can be a string or a module. If it is a string, it is used as module id to import the module. This module will be used to lookup the function to handle the request.

  3. The function. The name of the function used to handle the request. This element is optional. If it is omitted, the function name is derived from the request path. For instance, if the module exports a function called getDocument and the url mapping does not contain an action element, an incoming request with path /getDocument will be routed to that function. Requests to the root path are routed to the index function.

  4. Finally, a rule may contain any number of fixed arguments. These are simply passed to the handler function unchanged (see more on argument handling below).

Argument Handling

There are three ways to pass arguments to a request handler function:

  1. Defining them in urls. TBD

  2. Using capture groups in the url pattern. TBD

  3. Just adding stuff to the request path. TBD

Request Properties

TBD