Me Dev, You Jane

Introduction

NOTE: This tutorial is very very old and uses early versions of both Nitrogen and CouchDB and many things here may not work as advertised.

Hey. Today I'm going to show you how to create a really, really simple blog in a few minutes using the Nitrogen Web Framework and the CouchDB document system. I presume you have basic erlang skills but this should be simple for anyone. I also presume you have already seen the Nitrogen Screencasts and are familiar with the basic behavior of Nitrogen.

Ingredients

Here is what yo will need:

• Nitrogen
• CouchDB (or CouchDBX)
• Ecouch
• Extra Files

I assume that Ecouch and Nitrogen are set up in the library path (see here for installation info). If you need any further help on this see this post

If you are using Mac OS 10.5 I recommend you use my implementation of CouchDBX to get you started quickly.

First we create a new project in a location of your choosing with the command

nitrogen create myblog

In there you will see a basic project to get started with. Now unzip the Extra Files and copy the files to your project. You will see a basic template I have set up for you at wwwroot/template.html. You will also see the module json_obj wich I savagely stole from the StickyNotes tutorial. It's basically a module that will assist you dealing with JSON data in Erlang. As JSON's data types are incompatible with Erlang it's best to grab help wherever you can.

First we will need to start ecouch. Open up src/myblog_app.erl and modify start() to start up ecouch before nitrogen

start(_, _) -> 
  application:start(ecouch),
  nitrogen:start().

To start the development server open up a terminal to the project root, type in "./start.sh" and visit the website http://localhost:8000. You should see a nice website with the body "web_index body.". Whenever you change the code in the project you will have to recompile with the command "sync:go().".

CouchDB

First thing we want to do is create the database and our view. Open up CouchDB at http://127.0.0.1:5984/_utils/, create a new database and name it "myblog". Next we are going to need a convenient view for Nitrogen. We are going to create a really simple view that returns a simple array with first the title and then the body. This makes it easy for us when we need to map the data later in Nitrogen as you will see later. We are also going to use the field timestamp as a key so the data is in time order.

To do that we select "Custom Query" under "Select view". Expand the "View Code" flap and replace the map function with the following.

function(doc) {
  emit(doc.timestamp, [doc.title, doc.body]);
}

Select "Save As" and save as the design document: "nitrogen" and view name: "flat".

The Model

We could call the data from the pages themselves but I prefer to create a little model class to seperate the logic. Create the file blog_posts.erl inside src and export get_posts/0 and add_post/1. First create the get_post/1.

get_posts() ->
    {ok, Return} = ecouch:view_access("myblog", "nitrogen", "flat"),
    RawRows = json_obj:get_value("rows", Return),
    F = fun(X) ->
            json_obj:get_value("value", X)
    end,
    Rows = lists:map(F, RawRows),
    lists:reverse(Rows).

First of all we made a call to CouchDB using ecouch requesting the nitrogen/flat view for the myblog database. Now as Erlang has incompatible types to JSON there is a lot of ugly extra data in the raw return which looks like this

{obj,[{"total_rows",2},
          {"offset",0},
          {"rows",
           [{obj,[{"id",<<"b8ffeaa68f2fd4010a105ddc56460466">>},
                  {"key",123},
                  {"value",[<<"The Title">>,<<"TheBody">>]}]},
            {obj,[{"id",<<"53b075b3633f8d8b3654576806ef18b3">>},
                  {"key",321},
                  {"value",[<<"Another Title">>,<<"Another Body">>]}]}]}]}

Now thats not very pretty is it so we use the json_obj module to query the value of "rows" so we don't have to parse this data by hand. We then make a fun that does the same thing for the "value" field of a row and use the map function to call it on each of the rows. We then reverse the list so the latest post is first. After doing all this the result of the function would be as following:

[ [<<"Another Title">>,<<"Another Body">>], [<<"The Title">>,<<"TheBody">>] ]

Ahh... Much Nicer.

We also need to create the data so we add the add_post/1 method.

add_post({post, Title, Body}) ->
    JSONTemplate = {obj, []},
    WithTitle = json_obj:set_value("title", list_to_binary(Title), JSONTemplate),
    WithTitleAndBody = json_obj:set_value("body", list_to_binary(Body), WithTitle),
    Complete = json_obj:set_value("timestamp", calendar:time_to_seconds(now()), WithTitleAndBody),
    ecouch:doc_create("myblog", Complete).

This does not need much explanation. We start by creating an empty JSON object so that we can use the json_obj functions on it. We then add the Title and Body parameters to the object and create a timestamp as well. Finally we ask ecouch to create the document.

The Index Page

Now edit the file called src/pages/web_index.erl and edit the function body() to look like this.

body() ->
    Data = blog_posts:get_posts(),
    Map = [titleHeader@text, bodyLabel@text],
    #bind { id=simpleBinding, data=Data, map=Map, body=[
        #panel { class="post", body=[
            #h2 { class="title", id=titleHeader },
            #panel { class="entry", body=[
                #label{ id=bodyLabel }
            ]}
        ]}
    ]}.

The main thing here is the data binding. We first take the output from our model and bind it to Data. As you remember the output of the model is a list of lists. Then we create the Map to describe how the elements of those lists should should bind to the page elements. So we are saying that the first element should bind to the "text" variable on the element with the id "titleHeader". We then use the #bind record, which is a sort of a for loop, and feed to it the Data and the Map.

You should now be able to sync and go see the webpage. Of course you can not see anything yes as we have yet to create any data.

The Create Page

Next create a new page using the command nitrogen page /web/create in your project root. Open up the newly generate src/pages/web_create.erl and replace body():

body() ->
    Body = [
        #label { text="Title:" },
        #textbox{ id=titleTextBox, class="create_title", next=body },
        #label { text="Body (HTML Allowed):" }, 
        #textarea{ id=bodyTextArea, class="create_body" },
        #br {},
        #link{ id=commitButton, text="Submit", postback=commit }
    ],

    %% Validations
    wf:wire(commitButton, titleTextBox, #validate { validators=[
        #is_required { text="Required." },
        #min_length { length=2, text="Title must be at least 2 characters long." }
    ]}),
    wf:wire(commitButton, bodyTextArea, #validate { validators=[
        #is_required { text="Required." }
    ]}),

    %% Render
    wf:render(Body).

Next up add a new event() just above the line that says ´event(_) -> ok.´

event(commit) ->
    [Title] = wf:q(titleTextBox),
    [Body] = wf:q(bodyTextArea),
    blog_posts:add_post({post, Title, Body}),
    Message = wf:f("Post ~p created. <a href=\"/web/index\">click here</a> to see it.", [Title]),
    wf:flash(Message);

There is nothing really complicated here as we have made most of the work already in the model. We set up a textfield and a textarea. We then bind the commitButton the generate the commit event. We then set up Validations so we can't submit empty data.

The commit event takes the value of the titleTextBox and bodyTextArea and sends it's data to blog_posts:add_post/1. It then formats a nice message and flashes it to the user.

Now sync and visit the page. Enter the create page and try submitting empty field. Then fill in the data and add a few posts. Visit the Index page to view your posts.

Conclusion

Even though this is not a very thorough nor complex tutorial it really shows how easily you can use together these two projects and create something really powerful with little code.

If you hit a problem please check my completed code here