Helma Logo
main list history
previous version  overview  next version

Version 2 by hannes on 12. November 2009, 14:58

### 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