【原文】http://leafo.net/lapis/reference/lua_getting_started.html

生成一个新的项目

你可以在当前目录下运行下面的命令创建一个新的 Lua 项目:

1
$ lapis new --lua

默认的 nginx.conf 文件会引入 app.lua ,这个基础文件也是通过 lapis new 命令生成的。

app.lua 是整个项目的主入口,你可以引入其他的模块。事例如下:

1
2
3
4
5
6
7
8
9
-- app.lua
local lapis = require("lapis")
local app = lapis.Application()

app:get("/", function()
return "Welcome to Lapis " .. require("lapis.version")
end)

return app

这时候再启动服务器:

1
 lapis server

打开浏览器就可以访问 http://localhost:8080 这个地址了。

如果你想要改变访问的端口,可以创建一个 config.lua 文件。

在这个例子中,比如我想要 development 环境的访问端口改为 9090

1
2
3
4
5
6
-- config.lua
local config = require("lapis.config")

config("development", {
port = 9090
})

注意 : 后面我们会展开讲解如何配置一套完整的配置文件。

如果没有携带其他的参数 lapis server 正在运行的话,同时 development 环境正在跑着的话,系统会自动重新加载。(前提是 lapis_environment.lua 文件不存在)

Lapis 仅使用了少量的内建字段用于配置文件(比如:port),除此之外的字段你都可以使用。例如:

1
2
3
4
5
6
-- config.lua
local config = require("lapis.config")

config("development", {
greeting = "Hello world"
})

你可以通过 get 方法获取当前的配置信息。它会返回一个 Luatable 类型:

1
2
3
4
5
6
7
8
9
10
11
-- app.lua
local lapis = require("lapis")
local config = require("lapis.config").get()

local app = lapis.Application()

app:get("/", function(self)
return config.greeting .. " from port " .. config.port
end)

return app

创建一个 View

现在我们可以创建一个基础页面或者复杂的需要渲染的页面。Lapis 支持 etlua ,这是一个 Lua 模板语言,支持 Lua 混合 HTML 使用。

视图通常需要你准备相关的数据给它,然后它会生成 HTML,最终呈现在你面前。

Lapisview 的默认的路径是 views/ ,现在我们可以创建一个最普通的 view 文件 index.etlua

1
2
3

<h1>Hello world</h1>
<p>Welcome to my page</p>

我们发现跟常见的页面文件有些不一样,没有 <html><head><body> 标签。这里我们需要解释一下,view 不简单的负责页面的呈现,同时还负责页面的布局。

下面我们结合逻辑呈现我们的 view

1
2
3
4
5
6
7
8
9
10
11
-- app.lua
local lapis = require("lapis")

local app = lapis.Application()
app:enable("etlua")

app:get("/", function(self)
return { render = "index" }
end)

return app

etlua 默认是不开启的,如果你需要使用,需要通过方法将其打开。

我们可以在我们的 action 返回值中使用 render 参数去渲染指定的页面。在上面的例子中 "index" 会将自动加载 views/index.etlua 文件。

运行服务器后,在浏览器里输入指定的地址就可以查看刚刚渲染的页面了。

etlua 用法

当有以下标签的时候 etlua 会将 Lua 的代码注入进模板:

  • <% lua_code %> 常规的 Lua 代码引入,类似 PHP 里面的 <?php xxxx ?>
  • <%= lua_expression %> 表达式输出结果,但是 HTML 会被转义
  • <%- lua_expression %> 和上面的功能一样,不过不会转义 HTML

注意 :后续仍会继续介绍 etlua

下面我们会用一些事例来进一步了解上面的用法:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
-- app.lua
local lapis = require("lapis")

local app = lapis.Application()
app:enable("etlua")

app:get("/", function(self)
self.my_favorite_things = {
"Cats",
"Horses",
"Skateboards"
}

return { render = "list" }
end)

return app
1
2
3
4
5
6
7
<!-- views/list.etlua -->
<h1>Here are my favorite things</h1>
<ol>
<% for i, thing in pairs(my_favorite_things) do %>
<li><%= thing %></li>
<% end %>
</ol>

创建一个布局(Layout

在我们的页面当中 Layout 是一个独立的共享模板。你可以 DIY 你想要的效果。

下面我们创建一个 Layout 文件 views/layout.etlua :

1
2
3
4
5
6
7
8
9
10
11
12
<!-- views/layout.etlua -->
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<title><%= page_title or "My Page" %></title>
</head>
<body>
<h1>Greetings</h1>
<% content_for("inner") %>
</body>
</html>

content_for 是一个特殊的模板函数,你可以从视图里面向 Layout 发送数据。Lapis 会将渲染的结果塞进一个叫 innercontent 变量。 你会发现上面的例子中没有使用 etlua 的标签。因为 content_for 会将结果直接输出到缓冲区。

在视图(view)里面使用的变量和辅助函数在 Layout 里面也可以使用。

下面演示一下如何在 Lapis 应用中使用 Layout:

1
2
3
4
5
local app = lapis.Application()
app:enable("etlua")
app.layout = require "views.layout"

-- the rest of the application...

view 的使用上有一点语法上的区别,我们会通过名称引入进来,同时会赋值给一个模板对象。简单的讲 etlua 会将 .etlua 为后缀的文件转换成 Lua 可识别的文件。