xspager / sailor

A Lua MVC Web Framework.

#Sailor

A Lua MVC Framework. www.sailorproject.org

Features

• Compatible with Lua 5.1, Lua 5.2 and LuaJIT. (5.3 compatibility so far untested)
• Luarocks setup
• Runs over Apache2 (with mod_lua), NginX (openresty), Mongoose, Lighttpd, Xavante and Lwan web servers
• Using Windows, Mac or Linux systems
• Compatible with MySQL, PostgreSQL, SQLite and other databases supported by the luasql library
• MVC structure
• Parsing of Lua pages
• Routing
• Basic Object-relational mapping
• Validation
• Transactions
• App comes already shipped with Bootstrap
• Include, redirect
• Sessions, cookies
• Login module
• Easy deployment (unix only) -> sailor create "app name" /dir/to/app
• Form generation
• Lua at client (possible through a Lua=>JS virtual machine deployed with the app)
• Friendly urls
• Inspect function for better debugging => similar to a var dump
• Custom 404 pages
• Relations
• Model generation (reading from DB)
• CRUD generation (reading from model)
• Theme and layout (now you can have multiple layouts inside a theme. e.g. 1-column and 2-column)
• Integration with Busted for unit and functional tests for your app

Roadmap

• Integration with mod_lua's DB API and DB module refactor
• Improvements to the form and validation module

More about the motivation to build this project can be found here: http://etiene.net/10/sailor

Directory tree info

• /docs - this one is supposed to have documentation
• /lua-to-js-vms - different Lua->Javascript virtual machines for use of Lua on the browser with Sailor
• /rockspecs - Rockspec files for LuaRocks install
• /src - Lua modules with nice stuff from sailor and other places.
• /sailor - Sailor modules
• /sailor/blank-app - blank Sailor web app, can be copy-pasted as base for your own apps
• /test - apps for testing and demonstration purposes

Supported Environments

Sailor has been tested under Linux, Mac OS X and Windows and is currently compatible with Apache with mod_lua or mod_pLua, Nginx with ngx_lua, Lwan, Lighttpd with mod_magnet, or any CGI-enabled web server, like Civetweb, Mongoose and Xavante, if CGILua is present.

Installation

For Linux, see INSTALL_LINUX.md (Ubuntu) or INSTALL_LINUX_ARCH.md (Arch Linux)

For Windows, see INSTALL_WIN.md

For Mac, see INSTALL_MAC.md

Using Sailor

A default Sailor app will have the following directory tree structure:

• /conf - configuration files, open and edit them.
• /controllers - controllers you will make!
• /themes - default theme files.
• /models - models you will make!
• /pub - publicly accessible files (js libraries, for example)
• /runtime - temporary files generated during runtime.
• /tests - unit and functional tests
• /views - this is where your lua pages in .lp will go

Creating Pages

Go to /controllers and create your first controller! It should be a lua module. Name it whatever you want, our example is "site.lua". We will serve two pages, one accessible via /?r=site which will run site.index() by default and another one acessible via /?r=site/notindex.

local site = {}
local model = require "sailor.model"
function site.index(page)
  local foo = 'Hello world'
  local User = model("user")
  local u = User:new()
  u.username = "etiene"
  u.password = "a_password"
  local valid, err = u:validate() -- validate() will check if your attributes follow the rules!
  if not valid then
    foo = "Boohoo :("
  end

  -- Warning: this is a tech preview and some methods of model class do not avoid SQL injections yet.
  page:render('index',{foo=foo,name=u.username}) -- This will render /views/site/index.lp and pass the variables 'foo' and 'name'
end
function site.notindex(page)
  page:write('<b>Hey you!</b>')
end
return site

Go to /views, create a dir named 'site' to match your controller name and create your first page, our example is index.lp

<?=foo?>
<p>
  Hi, <?=name?>
</p>

For more information on what you can do with html and Lua Pages, visit http://keplerproject.github.io/cgilua/manual.html#templates

For more examples, you can check the test controller (/controllers/test.lua), the test views (/views/test/*) and the User model (/models/user.lua)

Documentation & Reference Manual

http://sailorproject.org/?r=docs

Contributing

Contributions are welcome! Just make a pull request :) Please try to follow the code style of the rest of the repository.

If you made an extension for Sailor and would like to share, please get in contact so I can add it to the website.

Thanks

This repository contains the following third-party MIT licensed code:

• LP Templates - http://keplerproject.github.io/cgilua/manual.html#templates
• Valua - https://github.com/sailorproject/valua
• Lua at client - https://github.com/felipedaragon/lua_at_client
• Moonshine - http://moonshinejs.org/
• Lua5.1.js - https://github.com/logiceditor-com/lua5.1.js
• Lua.vm.js - https://kripken.github.io/lua.vm.js/lua.vm.js.html
• Starlight - https://github.com/paulcuth/starlight

Suggestions, questions & hugs

Hugs! Not bugs. For bugs, fill an issue! :)

[e-mail]

https://twitter.com/etiene_d

Mail List & Support

Join our google group for mail list and support

If you are having trouble to get Sailor working or if you got it working using different specs, please make contact so we can exchange info and I can improve the manual. Thanks!