Leafo/Lapis项目中的etlua模板引擎详解

Leafo/Lapis项目中的etlua模板引擎详解

lapis A web framework for Lua and OpenResty written in MoonScript 项目地址: https://gitcode.com/gh_mirrors/la/lapis

什么是etlua模板引擎

etlua是一种嵌入式模板语言，它允许开发者在模板文件中直接嵌入Lua代码，通过执行这些代码来生成动态内容。在Lapis框架中，etlua被广泛用于HTML模板的动态渲染。

etlua模板文件使用.etlua作为扩展名，Lapis框架能够自动识别和加载这类文件。要使用etlua模板，首先需要在应用中启用它。

etlua基本语法

etlua提供了三种主要的标签语法来嵌入Lua代码：

1. <% lua_code %> - 执行Lua代码但不输出结果
2. <%= lua_expression %> - 执行Lua表达式并输出结果，结果会被HTML转义
3. <%- lua_expression %> - 执行Lua表达式并输出结果，结果不会被HTML转义

安全注意事项

在Web开发中，安全是首要考虑因素。当显示用户提供的数据时，必须特别注意HTML转义，以防止跨站脚本攻击(XSS)。<%= %>标签会自动进行HTML转义，而<%- %>则不会。因此，除非你明确知道自己在做什么，否则应该优先使用<%= %>。

在Lapis中使用etlua模板

从动作渲染模板

在Lapis中，动作(action)是处理特定路由请求的函数。动作通常会准备数据，然后决定如何渲染响应。通过返回一个包含render选项的表，可以指定要使用的模板。

app:match("/", function()
  return { render = "hello" }  -- 渲染views/hello.etlua
end)

如果路由有名称，可以简化设置：

app:match("hello", "/", function()
  return { render = true }  -- 自动使用路由名"hello"作为模板名
end)

向模板传递数据

动作中可以通过self表向模板传递数据：

app:match("/", function(self)
  self.pets = { "Cat", "Dog", "Bird" }
  return { render = "my_template" }
end)

在模板中可以直接访问这些变量：

<!-- views/my_template.etlua -->
<ul class="list">
<% for i, item in ipairs(pets) do %>
  <li><%= item %></li>
<% end %>
</ul>

模板中的辅助函数

模板中可以调用各种辅助函数，如url_for用于生成路由URL：

<a href="<%= url_for('index') %>">Return home</a>

所有在请求对象(self)上可用的方法都可以在模板中调用。

子模板渲染

为了提高代码复用性，可以使用render函数渲染子模板：

<% render("views.navigation") %>  <!-- 渲染views/navigation.etlua -->

可以向子模板传递额外参数：

<% render("templates.list_item", { number_value = value }) %>

etlua模板专用函数

etlua模板中提供了几个专用函数：

1. render(template_name, [params]) - 渲染子模板
2. widget(widget_instance) - 渲染Widget实例
3. element(name, ...) - 渲染HTML元素

这些函数直接输出到缓冲区，不需要使用输出标签。

EtluaWidget类参考

Lapis内部将.etlua文件转换为EtluaWidget类。开发者也可以直接使用这个类：

local widget = EtluaWidget:load([[<h1>Hello <%= username %></h1>]])
local result = widget({username = "Garf"}):render_to_string()

性能提示

etlua模板会被编译以提高性能。应避免在每个请求中都编译模板，最佳实践是缓存编译结果。

总结

etlua为Lapis提供了强大而灵活的模板渲染能力。通过合理使用模板继承、数据传递和安全输出，可以构建出既安全又易于维护的Web应用界面。理解etlua的工作原理和最佳实践，将帮助开发者更高效地使用Lapis框架。

lapis A web framework for Lua and OpenResty written in MoonScript 项目地址: https://gitcode.com/gh_mirrors/la/lapis