*Updated* to reflect modifications to the ORM (No “Model” suffix; fractured in Types, Functions, Relations)

These are very early days for Turbinado, so much change is going on… But here’s a quick tutorial on putting together a poor man’s page editor/manager in Turbinado.

### Build Turbinado

*Warning!*: With 6.10’s changes in dynamic plugins, Turbinado only builds with GHC 6.8 right now. Fixing this is next up in the dev queue.

You’ll need to have the following packages installed to have a go at installation:

– GHC 6.8 *(darcs)*

– haskell-src-exts *(darcs)*

– harp *(darcs)*

– hslogger *(git)*

– encoding *(darcs)*

– hsx *(darcs)*

– hs-plugins *(darcs)*

– http *(darcs)*

– HDBC *(git)*

– HDBC-PostgreSQL *(git)*

**Grab the code**

git clone git://github.com/alsonkemp/turbinado.git

**Build it**

With all of the packages installed, wait for a new moon, stand on tip-toes, and do the following:



runghc Setup.lhs configure runghc Setup.lhs build

### Configure It

cp Config/App.hs.sample Config/App.hs cp Config/Routes.hs.sample Config/Routes.hs

Edit App.hs and Routes.hs to taste.

### Create the Page table



CREATE TABLE page ( title character varying NOT NULL, content text NOT NULL, _id character varying(255) NOT NULL PRIMARY KEY, );

Updated: added PRIMARY KEY which is needed by the ORM generator.

### Generate the ORM models



runghc scripts/GenerateModels

You should now have an interesting file or two in App/Models. The files are organized as follows:

* App/Models/Bases/Comment.hs – all base Models inherit this.

* App/Models/Bases/AbcXyzType.hs – the representation of the database table *abc_xyz*. Don’t edit this! It’s autogenerated and your changes will get ignored on the next gen.

* App/Models/Bases/AbcXyzFunctions.hs – CRUD functions on *abc_xyz*. Don’t edit this! It’s autogenerated and your changes will get ignored on the next gen.

* App/Models/Bases/AbcXyzRelations.hs – functions on tables related to *abc_xyz*. Don’t edit this! It’s autogenerated and your changes will get ignored on the next gen.

* App/Models/AbcXyz.hs – the user configurable area of the AbcXyz. By default this just imports the above three tables. All of your custom *find*, *insert* and *update* methods go here.

A big shout out to .netTiers for pointing the way on building a code-generator ORM.

### Create your Layout

Just as in Rails, the Layout usually defines the majority of your sites page structure. See here for the Layout used for turbinado.org.

### Create your Page controller

The controller handles the request and sets up ViewData for the View to render/display. This little Page controller has the following functions/methods/actions:

index: list all Pages.

show: render one Page.

new: display a blank Page form.

create: take the submission of the ‘new’ action.

edit: display an existing Page in a form for editing.

save: take the submission of the ‘edit’ action.

Full version here. Here’s a snippet:



-- 'id' is an important function name in Haskell, so I use id' for the Page's "id". There's got -- to be a better solution -- This is the generated ORM for the 'page' table in the database. import qualified App.Models.Page -- Index lists out all of the pages -- setViewDataValue is used to store data for retrieval by the View. Idea lifted from ASP.NET -- http://msdn.microsoft.com/en-us/magazine/cc337884.aspx index :: Controller () index = do pages <- App.Models.Page.findAll --use ORM goodness to get all pages setViewDataValue "pages-list" $ map (\p -> (title p, _id p)) pages -- Show shows one page -- Notes: -- * The "id" is parsed from the request's path and put into the Settings. -- See: http://github.com/alsonkemp/turbinado-website/tree/master/Config/Routes.hs -- * getSetting returns a "Maybe a". getSetting_u is the unsafe version and returns just the "a". show :: Controller () show = do id' <- getSetting_u "id" p <- App.Models.Page.find id' setViewDataValue "page-title" (title p) setViewDataValue "page-content" (content p) -- snip -- save :: Controller () save = do id' <- getSetting_u "id" _title <- getParam_u "title" _content <- getParam_u "content" p <- App.Models.Page.find id' App.Models.Page.update p {title = _title, content = _content} redirectTo $ "/Page/Show/" ++ id'

### Create Your Views

This Controller requires 4 views:

* Index

* Show

* New

* Edit – this could probably be the same as New.

See here for pre-built views. Here’s the “Index” view (note: *this isn’t very sugary and that makes me **sad** *):



page = <div> <h1> Page Index </h1> <% do ls <- getViewDataValue_u "pages-list" :: View [(String, String)] mapM indexItem ls %> </div> -- fugly, but I'm still getting used to HSP-like templating indexItem (t,i) = return $ cdata $ unlines $ ["<div style='padding: 0pt 5px;'>" ," <a href=\"/Page/Show/" ++ i ++"\">" ," "++ t ," </a>" ,"</div>" ]

Here’s the “Show” view and it’s *pretty sugary*:



page = <div> <h1><% getViewDataValue_u "page-title" :: View String %></h1> <% getViewDataValue_u "page-content" :: View String %> </div>

### Run It

Start up Turbinado:



dist/build/turbinado/turbinado -p 1111

Browse to it: http://localhost:1111/Page/Index (it’ll take a couple of seconds to compile the Model, Controller and View)

### Examples!

There’s still lots of work to do on the ORM and on Documentation. As the code base matures, both should progress. Examples are a nice way to drive development forward and to engage the community, so let me know if you’d like to see anything in particular demonstrated and I’ll try to implement it.