From 2b993e8527c7c7c3b15ac7063b1b1c5b7c472598 Mon Sep 17 00:00:00 2001
From: JIN <i@imooc.me>
Date: Wed, 20 Jul 2022 19:44:04 +0800
Subject: [PATCH] add leaf custom tags translation (#686)

* add leaf custom tags translation
---
 docs/fluent/migration.zh.md |   2 +-
 docs/leaf/custom-tags.zh.md | 120 ++++++++++++++++++++++++++++++++++++
 mkdocs.yml                  |   1 +
 3 files changed, 122 insertions(+), 1 deletion(-)
 create mode 100644 docs/leaf/custom-tags.zh.md

diff --git a/docs/fluent/migration.zh.md b/docs/fluent/migration.zh.md
index b13df2ff..8fe1d090 100644
--- a/docs/fluent/migration.zh.md
+++ b/docs/fluent/migration.zh.md
@@ -93,6 +93,6 @@ try await app.autoMigrate()
 
 ## 下一步
 
-请查看[schema builder](schema.zh.md) 和 [query builder](query.zh.md) 指南，以了解更多迁移相关的信息。
+请查看[schema builder](schema.md) 和 [query builder](query.zh.md) 指南，以了解更多迁移相关的信息。
 
 
diff --git a/docs/leaf/custom-tags.zh.md b/docs/leaf/custom-tags.zh.md
new file mode 100644
index 00000000..b38ae2c3
--- /dev/null
+++ b/docs/leaf/custom-tags.zh.md
@@ -0,0 +1,120 @@
+# 自定义标签
+
+你可以遵循 [`LeafTag`](https://api.vapor.codes/leaf-kit/main/LeafKit/LeafTag/) 协议来创建自定义的 Leaf 标签。
+
+为了演示这一点，让我们看看创建一个 `#now` 标签来打印当前时间戳。标签还支持一个可选参数来指定日期格式。
+
+## `LeafTag`
+
+首先创建一个名为 `NowTag` 的类并遵循 `LeafTag` 协议。
+
+```swift
+struct NowTag: LeafTag {
+    
+    func render(_ ctx: LeafContext) throws -> LeafData {
+        ...
+    }
+}
+```
+
+现在我们来实现 `render(_:)` 方法。传递给该方法的 `LeafContext` 参数包含了我们需要的所有内容。
+
+```swift
+struct NowTagError: Error {}
+
+func render(_ ctx: LeafContext) throws -> LeafData {
+    let formatter = DateFormatter()
+    switch ctx.parameters.count {
+    case 0: formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
+    case 1:
+	     guard let string = ctx.parameters[0].string else {
+	         throw NowTagError()
+	     }
+	     formatter.dateFormat = string
+    default:
+	     throw NowTagError()
+	 }
+    
+    let dateAsString = formatter.string(from: Date())
+    return LeafData.string(dateAsString)
+}
+```
+
+!!! 建议
+    如果你的自定义标签用来渲染 HTML，你应该使你的自定义标记符合 `UnsafeUnescapedLeafTag`，这样 HTML 就不会被转义。别忘了检查或清除用户的任何输入。
+
+## 配置标签
+
+现在我们已经实现了 `NowTag`，我们只需要告诉 Leaf 就可以了。你可以像这样添加任何标签 - 即使它们来自一个单独的包。你通常在`configure.swift` 中做如下配置：
+
+```swift
+app.leaf.tags["now"] = NowTag()
+```
+
+就是这样！现在可以在 Leaf 中使用我们的自定义标签了。
+
+```leaf
+The time is #now()
+```
+
+## 上下文属性
+
+`LeafContext` 包含两个重要的属性。`parameters` 和 `data` 有我们需要的一切。
+
+ - `parameters`： 包含标签参数的数组。
+ - `data`：一个字典，包含传递给 `render(_:_:)` 方法作为上下文视图的数据。
+
+
+### Hello 标签示例
+
+要了解如何使用它，让我们使用这两个属性实现一个简单的 hello 标签。
+
+#### 使用 Parameters
+
+我们可以访问包含名称的第一个参数。
+
+```swift
+struct HelloTagError: Error {}
+
+public func render(_ ctx: LeafContext) throws -> LeafData {
+
+        guard let name = ctx.parameters[0].string else {
+            throw HelloTagError()
+        }
+
+        return LeafData.string("<p>Hello \(name)</p>'")
+    }
+}
+```
+
+```leaf
+#hello("John")
+```
+
+#### 使用 Data
+
+我们可以通过使用 data 属性中的 ”name“ 键来访问 name 值。
+
+```swift
+struct HelloTagError: Error {}
+
+public func render(_ ctx: LeafContext) throws -> LeafData {
+
+        guard let name = ctx.data["name"]?.string else {
+            throw HelloTagError()
+        }
+
+        return LeafData.string("<p>Hello \(name)</p>'")
+    }
+}
+```
+
+```leaf
+#hello()
+```
+
+控制器：
+
+```swift
+return req.view.render("home", ["name": "John"])
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index 2edcff15..317edb90 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -127,6 +127,7 @@ plugins:
           Transactions: 事务
           Schema: 模式
           Leaf: Leaf
+          Custom Tags: 自定义标签
           Redis: Redis
           Advanced: 进阶
           Middleware: 中间件