bamboo-2009.6.25: readme.md

# Bamboo: a simple blog middleware on hack

Bamboo is a port of [Panda](http://github.com/nfjinjing/panda/tree), but runs on top of Hack. It's an experimental project but quite portable.

## Features

### plain text as data source

    db
    |---- blog
    |     |---- 08-09-01 first post
    |     |---- 09-09-02 learn javascript.html
    |
    |---- tag
    |     |---- programming
    |     |---- funny
    |
    |---- static
          |---- About

### simple config

    blog_title    = C大调
    blog_subtitle = 野猫不吃薯片
    host_name     = jinjing.easymic.com
    author_email  = nfjinjing@gmail.com

    navigation    = About
    per_page      = 7
    sidebar       = Blogroll.md
    favicon       = bamboo_icon.png

### hacker friendly

* posts are in plain text
* SCM for publishing / data managing ( not really a feature, but a design goal from the beginning )
* blindly follows the KISS principle from code to UI: be a simple blog, no more no less

### modular

By it's middleware nature, bamboo could be used with other hack middleware to achieve extensibility; Bamboo plugins are also middleware, so they can be used not only in bamboo, but any other CMS like web application.

## Demo

### blog

[Jinjing's blog](http://jinjing.easymic.com) source is available as a git repo:

    git clone git://github.com/nfjinjing/jinjing-blog.git

Or [browser](http://github.com/nfjinjing/jinjing-blog/tree/master) online

Note: This blog is using the Kibro handler. It's running under lighttpd and in fcgi. Definitely more robust, but require some set up work. 

### config

[jinjing's blog config file](http://github.com/nfjinjing/jinjing-blog/blob/401a541443d88bbf8d844874c1473d4b3bc81784/config/site.txt)

## Easy install in 3 steps

### 1. update cabal

    cabal update

### 2. install bamboo

    cabal install happy
    cabal install bamboo-launcher

### 3. run

    mkdir myblog
    cd myblog
    bamboo

## Bird view architecture

    hack-interface :
      1. bamboo-hack-compatible-layer -- bamboo-controller -- bamboo-theme
      2. [ bamboo-plugins ]
      3. [ hack-middleware-stack ]

## Customize

bamboo can be customized in 3 ways:

### Theme

Theme is separated from the bamboo's controller, connected through an interface and a state.

Though theme could be pure, it has the type of
    
    data Interface = 
        Index
      | IndexFeed
      | Post
      | Static
      | Tag
      | TagFeed
      | Search
      deriving (Show, Eq)
    
    type Theme = Interface -> State -> IO Response

This makes theme creation an relatively complex task, since a theme author basically has to do everything: from html construction to model manipulation. But since state is passed purely and return type is in IO, it also provides the ultimate safety and flexibility to theme construction, something unmatched by any main stream web frameworks. Integrating twitter? no problem, do them in IO.

### Plugin

Plugin is a proper hack middleware, so it works on an upper layer of the blog engine. It has all the power of a middleware, i.e. intercept request and response, and also the limitation, e.g. no idea of the underlying data structure of the app.

Plugin can be used to to do customization on the env object, or transformation to the response body. An example plugin is [syntax highlighting](http://github.com/nfjinjing/bamboo-plugin-highlight), which could be done in the core, but would be more lightweight ( in terms of architecture design ) to be separated into a plugin.

You are hence not limited to use just bamboo-plugins to customize your blog, any hack-middleware which suite your need will do.

### Javascript / CSS

In `db/config/theme`, you can customize precisely which `js / css` files to use, this allows client side customization and also lightweight configuration without compilation.

## Links

* [Hack](http://github.com/nfjinjing/hack)
* [Hack Contrib](http://github.com/nfjinjing/hack-contrib)
* [bamboo-theme-blueprint](http://github.com/nfjinjing/bamboo-theme-blueprint)
* [bamboo-launcher](http://github.com/nfjinjing/bamboo-launcher)
* [bamboo-plugin-highlight](http://github.com/nfjinjing/bamboo-plugin-highlight)