Author: Rusty Klophaus(@rustyio), Jesse Gumm (@jessegumm)

# Nitrogen Handlers

Getting Started | API | Elements | Actions | Validators | Handlers | Configuration Options | About

Nitrogen Handlers

## Table of Contents

- 1 Handler Overview
- 2 nitrogen:handler(HandlerName, Config)
- 3 Common Handler Behavior Arguments
- 4 The Handlers

## 1 Handler Overview

Core Nitrogen behavior has been broken out into well-defined, pluggable behavior modules called handlers. Handlers allow you to easily substitute your own logic for things like session, security, routing, and others. Simply create a module that implements one of the existing behaviors, and register it to call `nitrogen:handler/2` between the `nitrogen:init_request/2` and `nitrogen:run/0` calls found inside the `nitrogen_xxx` (where `xxx` is the webserver used, for example 'mochiweb', 'yaws', 'cowboy', etc).

For example, let's add custom session and config handlers to our mochiweb install. To do so, let's add our handlers to `nitrogen_mochiweb:loop/1`:

    loop(Req) ->
      {ok, DocRoot} = application:get_env(mochiweb, document_root),
      RequestBridge = simple_bridge:make_request(mochiweb_request_bridge, Req),
      ResponseBridge = simple_bridge:make_response(mochiweb_response_bridge, {Req, DocRoot}),
      nitrogen:init_request(RequestBridge, ResponseBridge),
      nitrogen:handler(my_config_handler,[]),   %% Add custom config handler
      nitrogen:handler(my_session_handler,[]),  %% Add custom session handler
      nitrogen:run().

It may seem odd to you that we're not specifying which handler we're actually loading, but that's because the `nitrogen:handler/2` function determines, based on the `behavior()` defined within the handler module, which handler it is we're actually loading.

## 2 nitrogen:handler(HandlerName, Config)

`nitrogen:handler/2` is the way to function to connect your custom handler into Nitrogen's handler system. This function takes two arguments:

- `HandlerName` - The name of the module.
- `Config` - Any configuration settings for this handler. This variable could be just about anything, a proplist containing API keys or IP addresses of related servers (say for a session handler connected to an external memcache or something.

## 3 Common Handler Behavior Arguments

In all of the handler behavior functions are found two particular variables:

- `Config` - When a handler is initialized using `nitrogen:handler/2`, the second argument is `Config`, which is then passed into each handler function.
- `State` - The current state of the handler. Each handler maintains its own state.

## 4 The Handlers

Note: The `init/2` function is called on each handler in a specific order as defined in `wf_context:init_context/2`.

In the order they are loaded, here are all the handlers, and their documentation:

#### Core handlers:

- Config Handler - Controls how and from where the configuration settings are loaded.
- Log Handler - Controls the logging system for your Nitrogen app.
- Process Registry Handler - Controls how processes are tracked. The default backend for the process registry is nprocreg.

- Query Handler - Controls the how `wf:q` (and its siblings, `wf:qs`, `wf:mq`, etc), functions retrieve their values from the POST, GET, or other methods.

#### Stateful Handlers

- Session Handler - Controls how session information and variables are set, stored, and/or distributed.
- State Handler - Controls how the `wf:state` functions store and retrieve their values. The default uses a simple proplist.
- Identity Handler - Controls how the identity of the client is stored and retrieved. This is related to the `wf:user` functions.
- Role Handler - Controls how the roles of the client are stored and retrieved. This is related to the `wf:role` functions.

#### Handlers that possibly redirect

- Route Handler - Controls how Nitrogen routes requests to modules or static files.
- Security Handler - Controls whether or not a user has access to a resource, and if not, should determine what to do with the request.

Date: 2012-10-18 03:24:06 CDT

Author: Rusty Klophaus(@rustyio), Jesse Gumm (@jessegumm)

Org version 7.8.02 with Emacs version 23

Validate XHTML 1.0

## Comments

Note:To specify code blocks, just use the generic code block syntax:

    <pre><code>your code here</code></pre>

comments powered by Disqus