Request Dispatching

Basic Use

The ringo/webapp module provides a regular expression based request dispatcher. To use it, simply use the handleRequest function exported by ringo/webapp as JSGI app in your webapp's config.js file:

exports.app = require("ringo/webapp").handleRequest;

Since handleRequest is the default name Ringo assumes for JSGI apps it is enough to just use the module name:

exports.app = "ringo/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. Appending them as fixed arguments to a rule in the urls array as described in item 4. in the list above. This is useful for passing static arguments to a generic request handler function.

  2. Using RegExp capture groups in the url pattern. Any capturing parentheses in a rule's pattern will result in the part of the request path matching that group to be passed as argument to the function.

  3. Defining arguments in the function for any remaining request path elements. If a request matches a pattern and the request path contains additional elements not matched by the pattern, ringo/webapp checks if the handling function defines enough formal arguments to take these unmatched request path elements.

    If it does, each request path element will be passed to the function as individual argument. Else, the rule is considered as not matching and the next rule in the urls array is examined.

Request Properties

See API documentation for ringo/webapp/request.

edit this page | list all pages | go home