From b125e02d8d14a71ef52422ad93f60c2bb3e14b21 Mon Sep 17 00:00:00 2001
From: guqing <38999863+guqing@users.noreply.github.com>
Date: Tue, 2 Jul 2024 12:27:22 +0800
Subject: [PATCH] docs: add docs for template footer processor (#381)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

### What this PR does?
为 TemplateFooterProcessor 添加开发文档

see also https://github.com/halo-dev/halo/pull/6191

```release-note
None
```
---
 .../template-footer-processor.md              | 77 +++++++++++++++++++
 sidebars.js                                   |  1 +
 .../template-footer-processor.md              | 77 +++++++++++++++++++
 versioned_sidebars/version-2.17-sidebars.json |  1 +
 4 files changed, 156 insertions(+)
 create mode 100644 docs/developer-guide/plugin/api-reference/server/extension-points/template-footer-processor.md
 create mode 100644 versioned_docs/version-2.17/developer-guide/plugin/api-reference/server/extension-points/template-footer-processor.md

diff --git a/docs/developer-guide/plugin/api-reference/server/extension-points/template-footer-processor.md b/docs/developer-guide/plugin/api-reference/server/extension-points/template-footer-processor.md
new file mode 100644
index 0000000..7035c99
--- /dev/null
+++ b/docs/developer-guide/plugin/api-reference/server/extension-points/template-footer-processor.md
@@ -0,0 +1,77 @@
+---
+title: 主题端 Halo Footer 标签处理
+description: 提供扩展主题端 HTML 页面中的 <halo:footer/> 标签内容处理的方法。
+---
+
+Halo 为主题端模板提供了自定义标签 `<halo:footer/>` 的处理扩展点，以便可以添加额外的页脚内容如版权信息、备案号等。
+
+## 使用场景
+
+- 添加备案号
+- 添加版权信息
+- 添加统计代码
+- 添加自定义脚本
+- 添加自定义链接
+
+## 扩展点定义
+
+扩展 `<halo:footer/>` 标签的扩展点定义为 `TemplateFooterProcessor`，对应的 `ExtensionPoint` 类型为 `MULTI_INSTANCE`，即可以有多个实现类。
+
+```java
+public interface TemplateFooterProcessor extends ExtensionPoint {
+
+    Mono<Void> process(ITemplateContext context, IProcessableElementTag tag,
+        IElementTagStructureHandler structureHandler, IModel model);
+}
+```
+
+`TemplateFooterProcessor` 对应的 `ExtensionPointDefinition` 资源描述如下：
+
+```yaml
+apiVersion: plugin.halo.run/v1alpha1
+kind: ExtensionPointDefinition
+metadata:
+  name: template-footer-processor
+spec:
+  className: run.halo.app.theme.dialect.TemplateFooterProcessor
+  displayName: 页脚标签内容处理器
+  type: MULTI_INSTANCE
+  description: "提供用于扩展 <halo:footer/> 标签内容的扩展方式。"
+```
+
+即声明 `ExtensionDefinition` 自定义模型对象时对应的 `extensionPointName` 为 `template-footer-processor`。
+
+## 示例实现
+
+以下是一个简单的 TemplateFooterProcessor 插件实现示例：
+
+```java
+@Component
+public class FakeFooterCodeInjection implements TemplateFooterProcessor {
+
+  @Override
+  public Mono<Void> process(ITemplateContext context, IProcessableElementTag tag,
+    IElementTagStructureHandler structureHandler, IModel model) {
+    var factory = context.getModelFactory();
+    // regular footer text
+    var copyRight = factory.createText("<div>© 2024 Halo</div>");
+    model.add(copyRight);
+    return Mono.empty();
+  }
+}
+```
+
+声明 ExtensionDefinition 自定义模型对象时对应的 extensionPointName 为 template-footer-processor。
+
+```yaml
+apiVersion: plugin.halo.run/v1alpha1
+kind: ExtensionDefinition
+metadata:
+  name: custom-footer-extension
+spec:
+  extensionPointName: template-footer-processor
+  className: com.example.FakeFooterCodeInjection
+  displayName: "Custom Footer Extension"
+  description: "Adds custom footer content."
+  icon: 'some-icon'
+```
diff --git a/sidebars.js b/sidebars.js
index 8556bba..b1cd5c5 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -198,6 +198,7 @@ module.exports = {
                     "developer-guide/plugin/api-reference/server/extension-points/comment-widget",
                     "developer-guide/plugin/api-reference/server/extension-points/notifier",
                     "developer-guide/plugin/api-reference/server/extension-points/template-head-processor",
+                    "developer-guide/plugin/api-reference/server/extension-points/template-footer-processor",
                     "developer-guide/plugin/api-reference/server/extension-points/post-content",
                     "developer-guide/plugin/api-reference/server/extension-points/singlepage-content",
                     "developer-guide/plugin/api-reference/server/extension-points/username-password-authentication-manager",
diff --git a/versioned_docs/version-2.17/developer-guide/plugin/api-reference/server/extension-points/template-footer-processor.md b/versioned_docs/version-2.17/developer-guide/plugin/api-reference/server/extension-points/template-footer-processor.md
new file mode 100644
index 0000000..7035c99
--- /dev/null
+++ b/versioned_docs/version-2.17/developer-guide/plugin/api-reference/server/extension-points/template-footer-processor.md
@@ -0,0 +1,77 @@
+---
+title: 主题端 Halo Footer 标签处理
+description: 提供扩展主题端 HTML 页面中的 <halo:footer/> 标签内容处理的方法。
+---
+
+Halo 为主题端模板提供了自定义标签 `<halo:footer/>` 的处理扩展点，以便可以添加额外的页脚内容如版权信息、备案号等。
+
+## 使用场景
+
+- 添加备案号
+- 添加版权信息
+- 添加统计代码
+- 添加自定义脚本
+- 添加自定义链接
+
+## 扩展点定义
+
+扩展 `<halo:footer/>` 标签的扩展点定义为 `TemplateFooterProcessor`，对应的 `ExtensionPoint` 类型为 `MULTI_INSTANCE`，即可以有多个实现类。
+
+```java
+public interface TemplateFooterProcessor extends ExtensionPoint {
+
+    Mono<Void> process(ITemplateContext context, IProcessableElementTag tag,
+        IElementTagStructureHandler structureHandler, IModel model);
+}
+```
+
+`TemplateFooterProcessor` 对应的 `ExtensionPointDefinition` 资源描述如下：
+
+```yaml
+apiVersion: plugin.halo.run/v1alpha1
+kind: ExtensionPointDefinition
+metadata:
+  name: template-footer-processor
+spec:
+  className: run.halo.app.theme.dialect.TemplateFooterProcessor
+  displayName: 页脚标签内容处理器
+  type: MULTI_INSTANCE
+  description: "提供用于扩展 <halo:footer/> 标签内容的扩展方式。"
+```
+
+即声明 `ExtensionDefinition` 自定义模型对象时对应的 `extensionPointName` 为 `template-footer-processor`。
+
+## 示例实现
+
+以下是一个简单的 TemplateFooterProcessor 插件实现示例：
+
+```java
+@Component
+public class FakeFooterCodeInjection implements TemplateFooterProcessor {
+
+  @Override
+  public Mono<Void> process(ITemplateContext context, IProcessableElementTag tag,
+    IElementTagStructureHandler structureHandler, IModel model) {
+    var factory = context.getModelFactory();
+    // regular footer text
+    var copyRight = factory.createText("<div>© 2024 Halo</div>");
+    model.add(copyRight);
+    return Mono.empty();
+  }
+}
+```
+
+声明 ExtensionDefinition 自定义模型对象时对应的 extensionPointName 为 template-footer-processor。
+
+```yaml
+apiVersion: plugin.halo.run/v1alpha1
+kind: ExtensionDefinition
+metadata:
+  name: custom-footer-extension
+spec:
+  extensionPointName: template-footer-processor
+  className: com.example.FakeFooterCodeInjection
+  displayName: "Custom Footer Extension"
+  description: "Adds custom footer content."
+  icon: 'some-icon'
+```
diff --git a/versioned_sidebars/version-2.17-sidebars.json b/versioned_sidebars/version-2.17-sidebars.json
index 8a328b2..a56428e 100644
--- a/versioned_sidebars/version-2.17-sidebars.json
+++ b/versioned_sidebars/version-2.17-sidebars.json
@@ -183,6 +183,7 @@
                     "developer-guide/plugin/api-reference/server/extension-points/comment-widget",
                     "developer-guide/plugin/api-reference/server/extension-points/notifier",
                     "developer-guide/plugin/api-reference/server/extension-points/template-head-processor",
+                    "developer-guide/plugin/api-reference/server/extension-points/template-footer-processor",
                     "developer-guide/plugin/api-reference/server/extension-points/post-content",
                     "developer-guide/plugin/api-reference/server/extension-points/singlepage-content",
                     "developer-guide/plugin/api-reference/server/extension-points/username-password-authentication-manager"