Skip to content

Commit

Permalink
docs: add docs for template footer processor (#381)
Browse files Browse the repository at this point in the history
### What this PR does?
为 TemplateFooterProcessor 添加开发文档

see also halo-dev/halo#6191

```release-note
None
```
  • Loading branch information
guqing committed Jul 2, 2024
1 parent 9b87090 commit b125e02
Show file tree
Hide file tree
Showing 4 changed files with 156 additions and 0 deletions.
Original file line number Diff line number Diff line change
@@ -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'
```
1 change: 1 addition & 0 deletions sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
Original file line number Diff line number Diff line change
@@ -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'
```
1 change: 1 addition & 0 deletions versioned_sidebars/version-2.17-sidebars.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down

0 comments on commit b125e02

Please sign in to comment.