pc5kflswa
/
docs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add documentation for annotations form definition (#165)

Browse Source 
添加 Annotations Form 表单定义和使用的文档。

Fixes #154 

/kind documentation

```release-note
None
```
JohnNiang-patch-1
Ryan Wang 2 years ago committed by GitHub
parent 4634f74021
commit 1165cff265
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 311 additions and 1 deletions
Show Stats Download Patch File Download Diff File

89
docs/developer-guide/annotations-form.md
Unescape View File

@ -0,0 +1,89 @@
---
title: 元数据表单定义
---
在 Halo 2.0，所有的模型都包含了 `metadata.annotations` 字段，用于存储元数据信息。元数据信息可以用于存储一些自定义的信息，可以等同于扩展字段。此文档主要介绍如何在 Halo 中为具体的模型定义元数据编辑表单，至于如何在插件或者主题模板中使用，请看插件或者主题的文档。
定义元数据编辑表单同样使用 `FormKit Schema`，但和主题或插件的定义方式稍有不同，其中输入组件类型可参考 [表单定义](./form-schema.md)。
:::info 提示
因为 `metadata.annotations` 是一个键值都为字符串类型的对象，所以表单项的值必须为字符串类型。这就意味着，FormKit 的 `number`、`group`、`repeater` 等类型的输入组件都不能使用。
:::
## AnnotationSetting 资源定义方式
```yaml title="annotation-setting.yaml"
apiVersion: v1alpha1
kind: AnnotationSetting
metadata:
generateName: annotation-setting-
spec:
targetRef:
group: content.halo.run
kind: Post
formSchema:
- $formkit: "text"
name: "download"
label: "下载地址"
- $formkit: "text"
name: "version"
label: "版本"
```
以上定义为文章模型添加了两个元数据字段，分别为 `download` 和 `version`，分别对应了下载地址和版本号，最终效果：
![Annotation Setting Preview](/img/annotation-setting/annotation-setting-preview.png)
字段说明：
1. `metadata.generateName`：可以不做修改，最终会以这个值当做前缀生成一个唯一的名称。
2. `spec.targetRef`：模型的关联，即为哪个模型添加元数据表单，目前支持的模型可查看下方的列表。
3. `spec.formSchema`：表单的定义，使用 FormKit Schema 来定义。虽然我们使用的 YAML，但与 FormKit Schema 完全一致。
targetRef 支持列表：
| 对应模型 | group | kind |
| ---------- | ---------------- | ---------- |
| 文章 | content.halo.run | Post |
| 自定义页面 | content.halo.run | SinglePage |
| 文章分类 | content.halo.run | Category |
| 文章标签 | content.halo.run | Tag |
| 菜单项 | `""` | MenuItem |
| 用户 | `""` | User |
## 为多个模型定义表单
考虑到某些情况可能会同时为多个模型添加元数据表单，推荐在一个 `yaml` 文件中使用 `---` 来分割多个资源定义，如下：
```yaml title="annotation-setting.yaml"
apiVersion: v1alpha1
kind: AnnotationSetting
metadata:
generateName: annotation-setting-
spec:
targetRef:
group: content.halo.run
kind: Post
formSchema:
- $formkit: "text"
name: "download"
label: "下载地址"
- $formkit: "text"
name: "version"
label: "版本"
---
apiVersion: v1alpha1
kind: AnnotationSetting
metadata:
generateName: annotation-setting-
spec:
targetRef:
group: ""
kind: MenuItem
formSchema:
- $formkit: "text"
name: "icon"
label: "图标"
```

64
docs/developer-guide/theme/annotations.md
Unescape View File

@ -0,0 +1,64 @@
---
title: 模型元数据
---
在 [元数据表单定义](../annotations-form.md) 我们介绍了如何为模型添加元数据表单，此文档将介绍如何在主题模板中使用元数据。
我们在模板中专门为获取 annotations 数据提供了三个方法，可以更加方便的设置默认值和判断元数据字段是否存在。
## #annotations.get(extension,key)
### 描述
根据对象和元数据的 key 获取元数据的值。
### 示例
```html {4}
<div th:with="menu = ${menuFinder.getPrimary()}">
<ul th:with="menuItems = ${menu.menuItems}">
<li th:each="menuItem : ${menuItems}">
<i th:class="${#annotations.get(menuItem, 'icon')}"></i>
<a th:href="@{${menuItem.status.href}}" th:text="${menuItem.spec.displayName}"></a>
</li>
</ul>
</div>
```
## #annotations.getOrDefault(extension,key,defaultValue)
### 描述
根据对象和元数据的 key 获取元数据的值，同时支持设置默认值。
### 示例
```html {4}
<div th:with="menu = ${menuFinder.getPrimary()}">
<ul th:with="menuItems = ${menu.menuItems}">
<li th:each="menuItem : ${menuItems}">
<i th:class="${#annotations.getOrDefault(menuItem, 'icon', 'fa')}"></i>
<a th:href="@{${menuItem.status.href}}" th:text="${menuItem.spec.displayName}"></a>
</li>
</ul>
</div>
```
## #annotations.contains(extension,key)
### 描述
根据对象和元数据的 key 判断元数据是否存在。
### 示例
```html {4}
<div th:with="menu = ${menuFinder.getPrimary()}">
<ul th:with="menuItems = ${menu.menuItems}">
<li th:each="menuItem : ${menuItems}">
<i th:if="${#annotations.contains(menuItem, 'icon')}" th:class="${#annotations.get(menuItem, 'icon')}"></i>
<a th:href="@{${menuItem.status.href}}" th:text="${menuItem.spec.displayName}"></a>
</li>
</ul>
</div>
```

2
sidebars.js
Unescape View File

@ -111,6 +111,7 @@ module.exports = {
"developer-guide/theme/template-route-mapping", "developer-guide/theme/template-route-mapping",
"developer-guide/theme/static-resources", "developer-guide/theme/static-resources",
"developer-guide/theme/settings", "developer-guide/theme/settings",
"developer-guide/theme/annotations",
{ {
type: "category", type: "category",
label: "模板变量", label: "模板变量",
@ -153,6 +154,7 @@ module.exports = {
], ],
}, },
"developer-guide/form-schema", "developer-guide/form-schema",
"developer-guide/annotations-form",
// { // {
// type: "link", // type: "link",
// label: "REST API", // label: "REST API",

BIN
static/img/annotation-setting/annotation-setting-preview.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 190 KiB

89
versioned_docs/version-2.1/developer-guide/annotations-form.md
Unescape View File

@ -0,0 +1,89 @@
---
title: 元数据表单定义
---
在 Halo 2.0，所有的模型都包含了 `metadata.annotations` 字段，用于存储元数据信息。元数据信息可以用于存储一些自定义的信息，可以等同于扩展字段。此文档主要介绍如何在 Halo 中为具体的模型定义元数据编辑表单，至于如何在插件或者主题模板中使用，请看插件或者主题的文档。
定义元数据编辑表单同样使用 `FormKit Schema`，但和主题或插件的定义方式稍有不同，其中输入组件类型可参考 [表单定义](./form-schema.md)。
:::info 提示
因为 `metadata.annotations` 是一个键值都为字符串类型的对象，所以表单项的值必须为字符串类型。这就意味着，FormKit 的 `number`、`group`、`repeater` 等类型的输入组件都不能使用。
:::
## AnnotationSetting 资源定义方式
```yaml title="annotation-setting.yaml"
apiVersion: v1alpha1
kind: AnnotationSetting
metadata:
generateName: annotation-setting-
spec:
targetRef:
group: content.halo.run
kind: Post
formSchema:
- $formkit: "text"
name: "download"
label: "下载地址"
- $formkit: "text"
name: "version"
label: "版本"
```
以上定义为文章模型添加了两个元数据字段，分别为 `download` 和 `version`，分别对应了下载地址和版本号，最终效果：
![Annotation Setting Preview](/img/annotation-setting/annotation-setting-preview.png)
字段说明：
1. `metadata.generateName`：可以不做修改，最终会以这个值当做前缀生成一个唯一的名称。
2. `spec.targetRef`：模型的关联，即为哪个模型添加元数据表单，目前支持的模型可查看下方的列表。
3. `spec.formSchema`：表单的定义，使用 FormKit Schema 来定义。虽然我们使用的 YAML，但与 FormKit Schema 完全一致。
targetRef 支持列表：
| 对应模型 | group | kind |
| ---------- | ---------------- | ---------- |
| 文章 | content.halo.run | Post |
| 自定义页面 | content.halo.run | SinglePage |
| 文章分类 | content.halo.run | Category |
| 文章标签 | content.halo.run | Tag |
| 菜单项 | `""` | MenuItem |
| 用户 | `""` | User |
## 为多个模型定义表单
考虑到某些情况可能会同时为多个模型添加元数据表单，推荐在一个 `yaml` 文件中使用 `---` 来分割多个资源定义，如下：
```yaml title="annotation-setting.yaml"
apiVersion: v1alpha1
kind: AnnotationSetting
metadata:
generateName: annotation-setting-
spec:
targetRef:
group: content.halo.run
kind: Post
formSchema:
- $formkit: "text"
name: "download"
label: "下载地址"
- $formkit: "text"
name: "version"
label: "版本"
---
apiVersion: v1alpha1
kind: AnnotationSetting
metadata:
generateName: annotation-setting-
spec:
targetRef:
group: ""
kind: MenuItem
formSchema:
- $formkit: "text"
name: "icon"
label: "图标"
```

64
versioned_docs/version-2.1/developer-guide/theme/annotations.md
Unescape View File

@ -0,0 +1,64 @@
---
title: 模型元数据
---
在 [元数据表单定义](../annotations-form.md) 我们介绍了如何为模型添加元数据表单，此文档将介绍如何在主题模板中使用元数据。
我们在模板中专门为获取 annotations 数据提供了三个方法，可以更加方便的设置默认值和判断元数据字段是否存在。
## #annotations.get(extension,key)
### 描述
根据对象和元数据的 key 获取元数据的值。
### 示例
```html {4}
<div th:with="menu = ${menuFinder.getPrimary()}">
<ul th:with="menuItems = ${menu.menuItems}">
<li th:each="menuItem : ${menuItems}">
<i th:class="${#annotations.get(menuItem, 'icon')}"></i>
<a th:href="@{${menuItem.status.href}}" th:text="${menuItem.spec.displayName}"></a>
</li>
</ul>
</div>
```
## #annotations.getOrDefault(extension,key,defaultValue)
### 描述
根据对象和元数据的 key 获取元数据的值，同时支持设置默认值。
### 示例
```html {4}
<div th:with="menu = ${menuFinder.getPrimary()}">
<ul th:with="menuItems = ${menu.menuItems}">
<li th:each="menuItem : ${menuItems}">
<i th:class="${#annotations.getOrDefault(menuItem, 'icon', 'fa')}"></i>
<a th:href="@{${menuItem.status.href}}" th:text="${menuItem.spec.displayName}"></a>
</li>
</ul>
</div>
```
## #annotations.contains(extension,key)
### 描述
根据对象和元数据的 key 判断元数据是否存在。
### 示例
```html {4}
<div th:with="menu = ${menuFinder.getPrimary()}">
<ul th:with="menuItems = ${menu.menuItems}">
<li th:each="menuItem : ${menuItems}">
<i th:if="${#annotations.contains(menuItem, 'icon')}" th:class="${#annotations.get(menuItem, 'icon')}"></i>
<a th:href="@{${menuItem.status.href}}" th:text="${menuItem.spec.displayName}"></a>
</li>
</ul>
</div>
```

4
versioned_sidebars/version-2.1-sidebars.json
Unescape View File

@ -93,6 +93,7 @@
"developer-guide/theme/template-route-mapping", "developer-guide/theme/template-route-mapping",
"developer-guide/theme/static-resources", "developer-guide/theme/static-resources",
"developer-guide/theme/settings", "developer-guide/theme/settings",
"developer-guide/theme/annotations",
{ {
"type": "category", "type": "category",
"label": "模板变量", "label": "模板变量",
@ -134,7 +135,8 @@
"developer-guide/theme/code-snippets" "developer-guide/theme/code-snippets"
] ]
}, },
"developer-guide/form-schema" "developer-guide/form-schema",
"developer-guide/annotations-form"
] ]
}, },
{ {

Write Preview
Loading…
Cancel
Save