Jump to:   Routes   Authorization   Return values   Caching   Content-Language   Post-processing   SimpleBridge request object

Chicago Boss associates each URL with a function of a controller. The URL /foo/bar will call the function foo_controller:bar. Each controller module should go into your project's src/controller/ directory and the file name should start with the application name and end with "_controller.erl", e.g. "appname_my_controller.erl". Helper functions should go into your project's src/lib/ directory. Controllers can take one parameter or two parameters: the SimpleBridge request object, and an optional session ID (if sessions are enabled). Declare it like:

Or:

Each exported controller function takes two or three arguments:

• First argument: the HTTP request method as an atom, e.g. 'GET' or 'POST'
• Second argument: the list of slash-separated tokens after the action name in the URL.
• Third argument (optional): the result of a function named before_ in the controller

Example function clauses:

These function clauses act as templates for constructing URLs in the view; for each CamelCase variable, simply use the lower-cased underscored equivalent as the parameter name. To continue the example above, you can construct URLs to match the above controllers with the following view tags:

Template variables can of course be used in place of string literals.

Routes

Most routing takes place in the controller pattern-matching code. You can define additional routes in priv/my_application.routes. The file contains a list of erlang terms, one per line finished with a dot. Each term is a tuple with a URL or an HTTP status code as the first term, and a Location::proplist() as the second term.

The Location proplist must contain keys for controller and action. An optional application key will route requests across applications.

A few examples of routes:

Most routes directly render the specified action; however, routing across applications (as in the second example) results in a 302 redirect. Note that the {% url %} template tag will use the routes file to generate "pretty" URLs where appropriate.

Additional Location parameters will be matched against the variable names of the controller's token list. For example, if user_controller.erl contains:

Then the location [{controller, "user"}, {action, "profile"}, {user_id, "123"}] will invoke the "profile" action of user_controller and pass in "123" as the only token (that is, UserId). If a location parameter does not match any variables in the token list, it will be passed in as a query parameter (e.g. ?user_id=123).

Routing URLs may contain regular expresssions. For example, the following route will match all URLs that start with a digit:

Sub-expressions can be captured using parentheses and substituted with the atoms '$1', '$2', etc. For example, the following route will capture a string of digits and pass them in as the coupon_id parameter:

Alternatively, named groups may be used to identify captured sub-expressions. For example, the following route is equivalent to the one above:

The route expressions must match the entire URL. That is, the expressions are implicitly bookended with ^ and $.

To define a default action for a controller, simply add a default_action attribute to the controller like so:

Authorization

If an action takes three arguments, then the function before_/3 in your controller will be passed:

1. the action name as a string
2. the request method as an atom
3. the list of URL tokens

before_/3 should return one of:

Probably most common before_/3 looks like:

before_(_, _, _) ->
    my_user_lib:require_login(Req).

Which might return a tuple of user credential or else redirect to a login page. This way, if you want to require a login to a set of actions, just give those actions a User argument, and the actions will be login protected and have access to the User variable.

Return values

Whether or not it takes a third argument, a controller action should return with one of the following:

Caching

Caching should be a part of any scalability strategy. In addition to caching the results of database queries (see config), Chicago Boss can cache the list of variables returned from controller actions. CB can also cache entire rendered web pages, but in doing so you will lose the benefit of customizing the page contents with the _before variable, which is not cached.

To enable caching, first make sure the cache_enable is set to true in your configuration and that you've configured cache servers. At present only Memcached cache servers are supported, but additional adapters will be added in the future.

Next, define a cache_ function with the following arguments:

1. Action - the action name (a string)
2. Tokens - a list of tokens
3. AuthInfo (optional) - authorization information returned from the before_ filter (see Authorization)

The cache_ function should return one of:

• {vars, CacheOptions} - cache the variable list returned by the controller action
• {page, CacheOptions} - cache the rendered page contents
• none - don't cache

Finally, CacheOptions is a proplist possibly containing:

• seconds - length of time to cache the result, in seconds
• watch - a topic string defining a collection of records to watch for changes. When a change is observed, the cached data will be invalidated

Note that separate cache entries are created for each language as returned by lang_ (see Content-Language).

Example cache_ function:

Content-Language

CB application views can be multi-lingual. By default, the language served to the client is chosen by comparing the incoming Accept-Language header to the available translations in a given view (see "How Chicago Boss Chooses Which Language To Serve". This can be overridden in two ways:

1. Returning [{"Content-Language", Lang}] from each action in your controller
2. Defining a lang_ function in your controller which returns the chosen language

The lang_ function will be passed the name of the current action, and optionally the result of the before_ filter. This function should return one of:

• auto - automatically choose a language based on the Accept-Language header
• A string indicating the language choice ("en", "fr", etc.)

Post-processing

If it exists, a function called after_ in your controller will be passed the result that is about to be returned to the client. The 'after_' function takes two or three arguments:

1. The action name, as a string
2. The HTTP result tuple
3. The result of the before_ function, provided one exists

The after_ function should return a (possibly) modified HTTP result tuple. Result tuples may be one of:

SimpleBridge

Controller functions are passed a SimpleBridge request object (slightly modified for Boss's purposes). Useful functions in the request object include: