How Nitrogen processes requests – part 3

Last time we traced the steps that Nitrogen takes to initialize the Context and reached wf_core:run_catched function which builds the Response.

run_catched() ->
    % Get the handlers from querystring, if they exist...

    % Initialize all handlers...

    % Deserialize the event if available...

    % TODO - Check for access

    % Call the module...
    case wf_context:type() of
        first_request    ->
        postback_request ->
        static_file      ->

Firstly, this function updates the Context with the page State which comes from the browser in the http Request in serialized form.

deserialize_context() ->
    RequestBridge = wf_context:request_bridge(),
    Params = RequestBridge:post_params(),

    % Save the old handles...
    OldHandlers = wf_context:handlers(),

    % Deserialize page_context and handler_list if available...
    SerializedPageContext = proplists:get_value("pageContext", Params),
    [Page, Handlers] = case SerializedPageContext of
        undefined -> [wf_context:page_context(), wf_context:handlers()];
        Other -> wf_pickle:depickle(Other)

    % Config is not serialized, so copy config from old handler list to new
    % handler list.
    Handlers1 = copy_handler_config(OldHandlers, Handlers),

    % Create a new context...

    % Return the new context...

deserialize_context() uses RequestBridge:post_params() which knows how to read and parse the http request body.
RequestBridge uses cowboy_request_bridge.erl which implements interface specified by parametrized module (we discussed it here).

The APIs of cowboy_request_bridge.erl are mostly wrappers around functions in cowboy_http_req.erl module which allow to get http headers, body, url etc, from the http request.

Due to the fact that Cowboy tries to optimize performance and memory consumption it allows to read the request body only once, which means that cowboy_request_bridge.erl has to cache it when it reads it the first time and caches the copy in process dictionary.

The problem though is that cowboy_request_bridge.erl uses now() to generate unique cache key:

new_key() ->

now() is the VM blocking call so using it for key generation on a busy website might be a performance hit but this bit could be changed, it is not too big of a problem.

here is the example of parsed request body :


 <<"Disable All tabs">>}, 
 <<"Disable Some tabs">>},


notice that it contains the keys for “pageContext” and “eventContext” with pickled values and also nested hierarchy of control IDs.

and here is how the this pageContext looks like after it was deserialized with wf_pickle:depickle() function:

{page_context,"temp475270",index,[],comet} ;

here we have un-pickled page_context and a list of Handlers.

Nitrogen then adds page_context to the Context with:


and then applies the state of the handlers to the Context with:


and also deserialises Event information found in the request body with the following code:

update_context_with_event() ->
    SerializedEvent = wf:q(eventContext),
    Event = wf_pickle:depickle(SerializedEvent),
    % Update the Context...
    PageModule = wf_context:page_module(),
    IsPostback = is_record(Event, event_context),
    case {PageModule, IsPostback} of
        {static_file, _} -> update_context_for_static_file();
        {_, false}       -> update_context_for_first_request();
        {_, true}        -> update_context_for_postback_request(Event)

This code determines the type of request and saves this type into Context:

  • static_file (if the request was of a file with any extension)
  • first_request – dynamic request
  • postback_request

and finally, depending on the type of request we run the functions to generate dynamic html, process postback or return a static file:

 % Call the module...
    case wf_context:type() of
        first_request    ->
        postback_request ->
        static_file      ->

if, for example, we did the first request to “\” which will be mapped to “index” – the type of request will be first_request and when we reach run_first_request() function it will finally call main() function of the erlang module which implements the page (e.g. index.erl)

run_first_request() ->
    % Some values...
    Module = wf_context:event_module(),
    {module, Module} = code:ensure_loaded(Module),
    Data = Module:main(),

and this is where we finally reach the step which is described in Nitrogen introductory manual, here we call Module:main() which calls the page template:


    #template { file=filename:join([web_common:templates(), "onecolumn.html"])

template “onecolumn.html” has placeholders like [[[page:title()]]] and [[[page:body()]]]

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "">
<html xmlns="">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Nitrogen - [[[page:title()]]]</title>

and Nitrogen will call corresponding functions from index.erl module and substitute the placeholders with html generated by these calls.

Final thoughts:

Well, this was quite tedious process and it is probably pain to read. But, hopefully, this will answer some of questions about internal working of Nitrogen. (writing this surely helped me to understand some of the Nitrogen design decisions).

I honestly think that Nitrogen can’t be used effectively until you have some rough ideas about what is going on in its guts.

Nitrogen is complex but elegant framework and what we have discussed so far is just the part of the story – we only briefly touched on Erlang side of things.

There is also the second part of the puzzle which is happening on the browser side and implemented by nitrogen.js module. This is javascript library which is responsible for postbacks generation (via ajax), communicating with jQuery, events handling, page_context serialization, objects lookups and many other things. Maybe we will discuss all this in one of the future posts.

This entry was posted in custom Nitrogen elements, Erlang, Nitrogen, Nitrogen_Elements and tagged , , , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s