# vim: ts=2 sw=2 et ft=org
#+STYLE: <LINK href="stylesheet.css" rel="stylesheet" type="text/css" />
#+TITLE: Nitrogen Handlers
#+AUTHOR: Rusty Klophaus(@rustyio), Jesse Gumm (@jessegumm)
#+OPTIONS:   H:2 num:1 toc:1 \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
#+EMAIL: 

#+TEXT: [[file:./index.org][Getting Started]] | [[file:./api.org][API]] | [[file:./elements.org][Elements]] | [[file:./actions.org][Actions]] | [[file:./validators.org][Validators]] | *Handlers* | [[file:./config.org][Configuration Options]] | [[file:../about.org][About]]
#+HTML: <div class=headline>Nitrogen Handlers</div>

* 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=:

#+BEGIN_SRC erlang
  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().
#+END_SRC

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.

* 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.

* 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.

* 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:
  + [[./handlers/config.org][Config Handler]] - Controls how and from where the
      configuration settings are loaded.
  + [[./handlers/log.org][Log Handler]] - Controls the logging system for your
      Nitrogen app.
  + [[./handlers/process_registry.org][Process Registry Handler]] - Controls
      how processes are tracked. The default backend for the process registry
      is [[https://github.com/nitrogen/nprocreg][nprocreg]].
#  + [[./handlers/cache.org][Cache Handler]] - Controls the server-side caching
#      interface used with =wf:cache/[1-3]=. (not currently implemenented)
  + [[./handlers/query.org][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.
#  + [[./handlers/mail][Mail Handler]] - Controls how nitrogen will send email

*** Stateful Handlers
  + [[./handlers/session.org][Session Handler]] - Controls how session
      information and variables are set, stored, and/or distributed.
  + [[./handlers/state.org][State Handler]] - Controls how the =wf:state=
      functions store and retrieve their values. The default uses a simple
      proplist.
  + [[./handlers/identity.org][Identity Handler]] - Controls how the identity
      of the client is stored and retrieved. This is related to the =wf:user=
      functions.
  + [[./handlers/role.org][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
  + [[./handlers/route.org][Route Handler]] - Controls how Nitrogen routes
      requests to modules or static files.
  + [[./handlers/security.org][Security Handler]] - Controls whether or not a user
      has access to a resource, and if not, should determine what to do with
      the request.
