【原文】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 方法获取当前的配置信息。它会返回一个 Lua 的 table 类型：

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，最终呈现在你面前。

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

1
2
3
<!-- views/index.etlua -->
<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 会将渲染的结果塞进一个叫 inner 的 content 变量。 你会发现上面的例子中没有使用 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 可识别的文件。