MVC for Lua Web Development

Orbit

• Home
• Pages
• Reference
• Tutorial
• License

Orbit Tutorial

This tutorial shows how to create a simple blog application in Orbit, backed by a database. It's very simple because it does not include any "admin" pages; you have to add posts directly to the database (though you can do it through a Lua console, and this tutorial will show how), but there is an interface for commenting on posts.

The tutorial assumes you have already installed Orbit (preferrably as part of Kepler, or via LuaRocks, and already have a web server that supports WSAPI set up (the Xavante web server that comes with Kepler is a good choice).

Complete source code for this blog is in the samples folder of Orbit's distribution. If you have installed Orbit via Kepler or LuaRocks look inside the rocks folder of your installation.

Initialization

You should create a blog.lua file, which will be the main source file for our application. The first thing you should put in this file is the code to load Orbit and other libraries you are going to use in your app:

local orbit = require "orbit"
local orcache = require "orbit.cache"
local markdown = require "markdown"
local wsutil = require "wsapi.util"

In this example we are going to use Orbit's page cache, and the Markdown parser for marking up posts.

We will now create the blog application and set it as the global environment for the rest of the module:

local blog = setmetatable(orbit.new(), { __index = _G })
if _VERSION == "Lua 5.2" then
  _ENV = blog
else
  setfenv(1, blog)
end

orbit.new injects quite a lot of stuff in the blog module's namespace. The most important of these are the dispatch_get, dispatch_post, and model methods that let you define the main functionality of the application. It also defines a mapper variable that Orbit uses to create the models (Orbit initializes this variable to its default OR mapper). Finally, it defines default controllers for 404 and 500 HTTP error codes as the not_found and server_error variables, respectively. Override those if you want custom pages for your application.

Let's load a configuration script for the blog (a common pattern in applications). You can get this script from here.

wsutil.loadfile("blog_config.lua", blog)()

The next few lines load one of LuaSQL's database driver (defined in the configuration), and sets up Orbit's OR mapper.

local luasql = require("luasql." .. database.driver)
local env = luasql[database.driver]()
mapper.conn = env:connect(unpack(database.conn_data))
mapper.driver = database.driver

Orbit's mapper needs a database connection to use, and which driver you are using (currently only "sqlite3" and "mysql" are supported).

You need to initialize the mapper before creating your application's models because Orbit's mapper hits the database on model creation to get the schema. Speaking of schema, now is a good time to create your blogs' database. I will assume you are using SQLite3. Create a blog.db database with the following SQL script:

CREATE TABLE blog_post
       ("id" INTEGER PRIMARY KEY NOT NULL,
       "title" VARCHAR(255) DEFAULT NULL,
       "body" TEXT DEFAULT NULL,
       "n_comments" INTEGER DEFAULT NULL,
       "published_at" DATETIME DEFAULT NULL);

CREATE TABLE blog_comment
       ("id" INTEGER PRIMARY KEY NOT NULL,
       "post_id" INTEGER DEFAULT NULL,
       "author" VARCHAR(255) DEFAULT NULL,
       "email" VARCHAR(255) DEFAULT NULL,
       "url" VARCHAR(255) DEFAULT NULL,
       "body" TEXT DEFAULT NULL,
       "created_at" DATETIME DEFAULT NULL);

CREATE TABLE blog_page
       ("id" INTEGER PRIMARY KEY NOT NULL,
       "title" VARCHAR(30) DEFAULT NULL,
       "body" TEXT DEFAULT NULL);

Orbit's mapper uses the id field to identify objects in the database, so you need it for every kind of object you are mapping.

Finally, let's initialize Orbit's page cache before creating our models:

local cache = orbit.cache.new(blog, cache_path)

The page cache greatly speeds access to any page that you cache, but you need to be careful and invalidate the cache for a page when any content on that page changes. We will see how to cache and invalidate pages in the controller section of this tutorial.

Creating Models

Our blog application has three kinds of objects: posts, comments, and "static" pages (things like an "About" page for the blog, for example). It's no coincidence that we also have three tables in the database, each table maps to a kind of object our application handles, and for each kind we will create a model. We first create a model object for posts:

posts = blog:model "post"

The parameter for the model method is the name of a table in the database. The posts object that this method creates represents the collection of posts, and at the same time is a prototype for all posts (we will see the implications of that shortly). Orbit's mapper creates a rather functional object by itself: you can do posts:find(3), for example, and get the post with id 3, or posts:find_all("n_comments < ?", { 3, order = "published_at desc" }) and get a list of all posts with less than three comments, ordered by most recent to least.

You can use the predefined find methods for all queries to the database, but it helps to abstract common queries in your own methods. You can do that by adding methods to the posts object:

function posts:find_recent()
   return self:find_all("published_at is not null",
            { order = "published_at desc",
               count = recent_count })
end

The lines above add a find_recent method to the posts object that returns a list of the most recent published posts (the number is in the configuration script), ordered from most recent to least. The application is going to use this method to generate the list of posts in the home page, as well as the "Recent Posts" section of the blog's sidebar.

Another feature of our blog is going to be archive pages that show all posts of a certain month and year. We will define a method for that too:

function posts:find_by_month_and_year(month, year)
   local s = os.time({ year = year, month = month, day = 1 })
   local e = os.time({ year = year + math.floor(month / 12),
            month = (month % 12) + 1,
            day = 1 })
   return self:find_all("published_at >= ? and published_at < ?",
            { s, e, order = "published_at desc" })
end

This is a more complicated method, as we have to convert from a simple month and year to start and end dates in the standard Lua format. Finally, we will also define a method that returns all months (and years) that have posts, to later generate the links for the "Archive" section in the sidebar:

function posts:find_months()
   local months = {}
   local previous_month = {}
   local posts = self:find_all("published_at is not null", 
                               { order = "published_at desc" })
   for _, post in ipairs(posts) do
      local date = os.date("*t", post.published_at)
      if previous_month.month ~= date.month or
     previous_month.year ~= date.year then
     previous_month = { month = date.month, year = date.year,
        date_str = os.date("%Y/%m", post.published_at) }
     months[#months + 1] = previous_month
      end
   end
   return months
end

This method gets all posts in the database, ordered by date, and iterates over them storing the each unique pair of month and year in a list.

We can also define methods for individual post objects by defining methods in the posts object, the only difference is how they are used (you use find_recent by doing posts:find_recent(), but you will use find_comments by doing p:find_comments(), where p is a particular post object. We will define a method to retrieve all comments of a post:

function posts:find_comments()
   return comments:find_all_by_post_id{ self.id }
end

This method uses a predefined method of the comments object (which we will create shortly) that gets all comments with field post_id equal to the id of the current post (self.id). This method establishes a relation between posts and comments; a future version of Orbit's mapper will let you define these declaratively.

Creating the comments object is simple:

comments = blog:model "comment"

Let's just add a convenience method for comments that build the comment's link from the its data:

function comments:make_link()
   local author = self.author or strings.anonymous_author
   if self.url and self.url ~= "" then
      return "" .. author .. ""
   elseif self.email and self.email ~= "" then
      return "" .. author .. ""
   else
      return author
   end
end

The pages object is even simpler, the default functionality provided by Orbit's mapper is enough, so we just create it with model:

pages = blog:model "pages"

This concludes the "model" part of our application. We can now move on to defining the applications' page flow, by defining controllers and mapping them to URLs.

Defining Controllers

Controllers are the interface between the web and your application. With Orbit you can map the path part of your application's URLs (in http://myserver.com/myapp.ws/foo/bar the path is /foo/bar, for example) to controllers. In Lua terms, an Orbit controller is a function that receives a request/response object (usually called web) plus parameters extracted from the path, and returns text that is sent to the client (usually HTML, but can be XML, or even an image).

You map paths to controllers with the dispatch_get and dispatch_post methods, for GET and POST requests, respectively. The first parameter to these methods is the controller, a Lua function, and all the other parameters are mapping patterns, written using Lua's string matching syntax, so one controller can answer to multiple mappings.

Below is the controller for the main page of the blog:

function index(web)
   local ps = posts:find_recent()
   local ms = posts:find_months()
   local pgs = pgs or pages:find_all()
   return render_index(web, { posts = ps, months = ms,
              recent = ps, pages = pgs })
end

blog:dispatch_get(cache(index), "/", "/index") 

The last line sets up the mapping between the index function and the root of the application. The call to cache sets up page caching for this controller, using the cache we created earlier (this is another common Lua idiom, functions as decorators).

The index controller shows all recent posts, and is pretty straightforward. It just fetches the required model data from the database, then calls an auxiliary function (called a view in MVC terminology) to render the actual HTML code.

Another important controller is the one that shows single posts:

function view_post(web, post_id, comment_missing)
   local post = posts:find(tonumber(post_id))
   if post then
      local recent = posts:find_recent()
      local pgs = pages:find_all()
      post.comments = post:find_comments()
      local months = posts:find_months()
      return render_post(web, { post = post, months = months,
                recent = recent, pages = pgs,
                comment_missing = comment_missing })
   else
      return not_found(web)
   end
end

blog:dispatch_get(cache(view_post), "/post/(%d+)")

Here we map all paths like /post/53 to the view_post controller. The pattern captures the number, and this is passed along to the controller by Orbit. For /post/53, the controller receives the string "53" as post_id and uses this to fetch the corresponding post. Again, HTML rendering is factored out to another function, and this controller is cached.

If no post with that id is found then the default controller for missing pages gets called, blog.not_found (orbit.app put it in the blog namespace). Orbit also calls this controller is it does not find a valid match for the path. Another default controller is server_error, called when any unprotected error happens in controller/view code.

Archives and pages are similar in structure:

function view_archive(web, year, month)
   local ps = posts:find_by_month_and_year(tonumber(month),
                       tonumber(year))
   local months = posts:find_months()
   local recent = posts:find_recent()
   local pgs = pages:find_all()
   return render_index(web, { posts = ps, months = months,
              recent = recent, pages = pgs })
end

blog:dispatch_get(cache(view_archive), "/archive/(%d%d%d%d)/(%d%d)")

function view_page(web, page_id)
   local page = pages:find(tonumber(page_id))
   if page then
      local recent = posts:find_recent()
      local months = posts:find_months()
      local pgs = pages:find_all()
      return render_page(web, { page = page, months = months,
             recent = recent, pages = pgs })
   else
      not_found(web)
   end
end

blog:dispatch_get(cache(view_page), "/page/(%d+)")

The archives use the same layout as the index, so they reuse its HTML generator. Archives also extract two parameters from the path, the month and the year, so paths are like /archive/2008/05.

Finally, you can also set up Orbit to serve static files with the dispatch_static convenience method:

blog:dispatch_static("/head%.jpg", "/style%.css")

These are also patterns, so the dots are escaped. You can set up a whole folder in your application as static with blog:dispatch_static("/templates/.+"). Orbit always looks for the files in your application's folder. Of course you are free to let your application only handle dynamic content and let your web server serve static content; dispatch_static is just a convenience to have "zero-configuration" applications.

There is one controller left, for adding comments. This one will answer to POST instead of GET:

function add_comment(web, post_id)
   local input = web.input
   if string.find(input.comment, "^%s*$") then
      return view_post(web, post_id, true)
   else
      local comment = comments:new()
      comment.post_id = tonumber(post_id)
      comment.body = markdown(input.comment)
      if not string.find(input.author, "^%s*$") then
     comment.author = input.author
      end
      if not string.find(input.email, "^%s*$") then
     comment.email = input.email
      end
      if not string.find(input.url, "^%s*$") then
     comment.url = input.url
      end
      comment:save()
      local post = posts:find(tonumber(post_id))
      post.n_comments = (post.n_comments or 0) + 1
      post:save()
      cache:invalidate("/")
      cache:invalidate("/post/" .. post_id)
      cache:invalidate("/archive/" .. os.date("%Y/%m", post.published_at))
      return web:redirect(web:link("/post/" .. post_id))
   end
end

blog:dispatch_post(add_comment, "/post/(%d+)/addcomment")

The add_comment controller first validates the input, delegating to view_post if the comment field is empty (which will show an error message in the page). You access POST parameters via the web.input table, which is conveniently aliased to an input local variable.

The controller creates a new comment object and fills it with data, then saves it to the database. It also updates the post object to increase the number of comments the post has by one, and also saves it. It then proceeds to invalidate (in the cache) all pages that may show this information: the index, the post's page, and the archives for this particular post. Finally, it redirects to the post's page, which will show the new comment. This is a common idiom in web programming called POST-REDIRECT-GET, where every POST is followed by a redirect to a GET. This avoids double posting in case the user hits reload.

The only thing left now is the HTML generation itself. This is the topic of the next section.

Views: Generating HTML

Views are the last component of the MVC triad. For Orbit views are just simple functions that generate content (usually HTML), and are strictly optional, meaning you can return content directly from the controller. But it's still good programming practice to separate controllers and views.

How you generate content is up to you: concatenate Lua strings, use table.concat, use a third-party template library... Orbit provides programmatic HTML/XML generation through orbit.htmlify, but you are free to use any method you want. In this tutorial we will stick with programmatic generation, though, as the other methods (straight strings, Cosmo, etc.) are thoroughly documented elsewhere.

When you htmlify a function, Orbit changes the function's environment to let you generate HTML by calling the tags as functions. It's better to show how it works than to explain, so here is the basic view of the blog application, layout:

function layout(web, args, inner_html)
   return html{
      head{
     title(blog_title),
     meta{ ["http-equiv"] = "Content-Type",
        content = "text/html; charset=utf-8" },
     link{ rel = 'stylesheet', type = 'text/css', 
        href = web:static_link('/style.css'), media = 'screen' }
      },
      body{
     div{ id = "container",
        div{ id = "header", title = "sitename" },
        div{ id = "mainnav",
           _menu(web, args)
        }, 
            div{ id = "menu",
           _sidebar(web, args)
        },  
        div{ id = "contents", inner_html },
        div{ id = "footer", copyright_notice }
     }
      }
   } 
end

This view is a decorator for other views, and generates the boilerplate for each page in the blog (header, footer, sidebar). You can see the HTML-generating functions througout the code, such as title, html, head, div. Each takes either a string or a table, and generates the corresponding HTML. If you pass a table, the array part is concatenated and used as the content, while the hash part os used as HTML attributes for that tag. A tag with no content generates a self-closing tag (meta and link in the code above).

Of note in the code above are the calls to web:static_link and to the _menu and _sidebar functions. The static_link method generates a link to a static resource of the application, stripping out the SCRIPT_NAME from the URL (for example, if the URL is http://myserver.com/myblog/blog.ws/index it will return /myblog/style.css as the link).

The _menu and _sidebar functions are just helper views to generate the blog's menubar and sidebar:

function _menu(web, args)
   local res = { li(a{ href= web:link("/"), strings.home_page_name }) }
   for _, page in pairs(args.pages) do
      res[#res + 1] = li(a{ href = web:link("/page/" .. page.id), page.title })
   end
   return ul(res)
end

function _sidebar(web, args)
   return {
      h3(strings.about_title),
      ul(li(about_blurb)),
      h3(strings.last_posts),
      _recent(web, args),
      h3(strings.blogroll_title),
      _blogroll(web, blogroll),
      h3(strings.archive_title),
      _archives(web, args)
   }
end

Here you see a mixture of standard Lua idioms (filling a table and passing it to a concatenation function) and Orbit's programmatic HTML. They also use the web:link method, which generates intra-application links. The sidebar function uses a few more convenience functions, for better factoring:

function _blogroll(web, blogroll)
   local res = {}
   for _, blog_link in ipairs(blogroll) do
      res[#res + 1] = li(a{ href=blog_link[1], blog_link[2] })
   end
   return ul(res)
end

function _recent(web, args)
   local res = {}
   for _, post in ipairs(args.recent) do
      res[#res + 1] = li(a{ href=web:link("/post/" .. post.id), post.title })
   end
   return ul(res)
end

function _archives(web, args)
   local res = {}
   for _, month in ipairs(args.months) do
      res[#res + 1] = li(a{ href=web:link("/archive/" .. month.date_str), 
                blog.month(month) })
   end
   return ul(res)
end

Notice how these functions do not call anything in the model, just using whichever data was passed by them (all the way from the controller).

We can now get to the main view functions. Let's start with the easiest, and smallest, one, to render pages:

function render_page(web, args)
   return layout(web, args, div.blogentry(markdown(args.page.body)))
end

This is a straightforward call to layout, passing the body of the page inside a div. The only thing of note is the div.blogentry syntax, which generates a div with a class attribute equal to "blogentry", instead of a straight div.

Moving on, we will now write the view for index pages (and archive pages):

function render_index(web, args)
   if #args.posts == 0 then
      return layout(web, args, p(strings.no_posts))
   else
      local res = {}
      local cur_time
      for _, post in pairs(args.posts) do
     local str_time = date(post.published_at)
     if cur_time ~= str_time then
        cur_time = str_time
        res[#res + 1] = h2(str_time)
     end
     res[#res + 1] = h3(post.title)
     res[#res + 1] = _post(web, post)
      end
      return layout(web, args, div.blogentry(res))
   end
end

Again we mix Lua with programmatic generation, and factor part of the output (the HTML for the body of the posts themselves) to another function (we will be able to reuse this function for the single-post view). The only unusual piece of logic is to implement fancier dates, the code only prints a date when it changes, so several posts made in the same day appear under the same date.

The _post helper is pretty straightforward:

function _post(web, post)
   return {
      markdown(post.body),
      p.posted{ 
     strings.published_at .. " " .. 
        os.date("%H:%M", post.published_at), " | ",
     a{ href = web:link("/post/" .. post.id .. "#comments"), strings.comments ..
        " (" .. (post.n_comments or "0") .. ")" }
      }
   }
end

Now we can finally move to the piece-de-resistance, the view that renders single posts, along with their comments, and the "post a comment" form:

function render_post(web, args)
   local res = { 
      h2(span{ style="position: relative; float:left", args.post.title }
     .. " "),
      h3(date(args.post.published_at)),
      _post(web, args.post)
   }
   res[#res + 1] = a{ name = "comments" }
   if #args.post.comments > 0 then
      res[#res + 1] = h2(strings.comments)
      for _, comment in pairs(args.post.comments) do
     res[#res + 1 ] = _comment(web, comment)
      end
   end
   res[#res + 1] = h2(strings.new_comment)
   local err_msg = ""
   if args.comment_missing then
      err_msg = span{ style="color: red", strings.no_comment }
   end
   res[#res + 1] = form{
      method = "post",
      action = web:link("/post/" .. args.post.id .. "/addcomment"),
      p{ strings.form_name, br(), input{ type="text", name="author",
     value = web.input.author },
         br(), br(),
         strings.form_email, br(), input{ type="text", name="email",
     value = web.input.email },
         br(), br(),
         strings.form_url, br(), input{ type="text", name="url",
     value = web.input.url },
         br(), br(),
         strings.comments .. ":", br(), err_msg,
         textarea{ name="comment", rows="10", cols="60", web.input.comment },
     br(),
         em(" *" .. strings.italics .. "* "),
         strong(" **" .. strings.bold .. "** "), 
         " [" .. a{ href="/url", strings.link } .. "](http://url) ",
         br(), br(),
         input.button{ type="submit", value=strings.send }
      }
   }
   return layout(web, args, div.blogentry(res))
end

This is a lot of code to digest at once, so let's go piece by piece. The first few lines generate the body of the post, using the _post helper. Then we have the list of comments, again with the body of each comment generated by a helper, _comment. In the middle we have an error message that is generated if the user tried to post an empty comment, and then the "add a comment" form. A form needs a lot of HTML, so there's quite a lot of code, but it should be self-explanatory and is pretty basic HTML (making it pretty is the responsibility of the style sheet).

The _comment helper is pretty simple:

function _comment(web, comment)
   return { p(comment.body),
      p.posted{
     strings.written_by .. " " .. comment:make_link(),
     " " .. strings.on_date .. " " ..
        time(comment.created_at) 
      }
   }
end

Finally, we need to set all of these view functions up for programmatic HTML generation:

orbit.htmlify(blog, "layout", "_.+", "render_.+")

The orbit.htmlify function takes a table and a list of patterns, and sets all functions in that table with names that match one of the patterns up for HTML generation. Here we set the layout function, all the render_ functions, and all the helpers (the functions starting with _).

We end the file by returning the module:

return blog

Deployment

For this part of the tutorial it is better if you go to the samples/blog folder of Orbit's distribution (again, look inside the rocks folder if you installed with Kepler or LuaRocks). An Orbit application is a WSAPI application, so deployment is very easy, you can just copy all the application's files (blog.lua, blog_config.lua, blog.db, head.jpg, and style.css) to a folder in your web server's docroot (if you installed Kepler, to a folder inside kepler/htdocs), and create a launcher script in this folder. The launcher script is simple (call it blog.ws):

#!/usr/bin/env wsapi.cgi
return require "blog"

Depending on your configuration, you might need to install the luasql-sqlite3 and markdown rocks before running the application. Now just start Xavante, and point your browser to blog.ws, and you should see the index page of the blog. If you created a blog.db from scratch you are not going to see any posts, though. The blog application in `samples/blog' includes a blog.db filled with random posts and comments.