Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update readme #103

Merged
merged 1 commit into from
May 10, 2024
Merged

docs: update readme #103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
261 changes: 133 additions & 128 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,31 @@
# plugin-moments

Halo 2.0 的瞬间管理插件, 支持在 Console 进行管理以及为主题端提供 `/moments` 页面路由。
Halo 2.0 的瞬间管理插件，提供一个轻量级的内容发布功能，支持发布图文、视频、音频等内容。

![Preview](./images/plugin-moments-preview.png)

## 使用方式

1. 下载，目前提供以下两个下载方式：
- GitHub Releases：访问 [Releases](https://github.com/halo-sigs/plugin-moments/releases) 下载 Assets 中的 JAR 文件。
- Halo 应用市场：<https://halo.run/store/apps/app-SnwWD>
- GitHub Releases：访问 [Releases](https://github.com/halo-sigs/plugin-moments/releases) 下载 Assets 中的 JAR 文件。
2. 安装，插件安装和更新方式可参考：<https://docs.halo.run/user-guide/plugins>
3. 安装完成之后，访问 Console 左侧的**瞬间**菜单项，即可进行管理。
4. 前台访问地址为 `/moments`，需要注意的是，此插件需要主题提供模板（moments.html）才能访问 `/moments`。
5. 此插件也提供了 RSS 订阅的路由，可以访问 `/moments/rss.xml`。

## 主题适配
## 开发环境

目前此插件为主题端提供了 `/moments` 路由，模板为 `moments.html`，也提供了 [Finder API](https://docs.halo.run/developer-guide/theme/finder-apis)，可以将瞬间列表渲染到任何地方。
插件开发的详细文档请查阅：<https://docs.halo.run/developer-guide/plugin/introduction>

## 开发环境
所需环境：

1. Java 17
2. Node 18
3. pnpm 8
4. Docker (可选)

克隆项目：

```bash
git clone [email protected]:halo-sigs/plugin-moments.git
Expand All @@ -29,6 +39,10 @@ git clone [email protected]:{your_github_id}/plugin-moments.git
cd path/to/plugin-moments
```

### 运行方式 1（推荐）

> 此方式需要本地安装 Docker

```bash
# macOS / Linux
./gradlew pnpmInstall
Expand All @@ -37,6 +51,22 @@ cd path/to/plugin-moments
./gradlew.bat pnpmInstall
```

```bash
# macOS / Linux
./gradlew haloServer

# Windows
./gradlew.bat haloServer
```

执行此命令后，会自动创建一个 Halo 的 Docker 容器并加载当前的插件，更多文档可查阅：<https://docs.halo.run/developer-guide/plugin/basics/devtools>

### 运行方式 2

> 此方式需要使用源码运行 Halo

编译插件：

```bash
# macOS / Linux
./gradlew build
Expand All @@ -49,40 +79,52 @@ cd path/to/plugin-moments

```yaml
halo:
plugin:
runtime-mode: development
classes-directories:
- "build/classes"
- "build/resources"
lib-directories:
- "libs"
fixedPluginPath:
- "/path/to/plugin-moments"
plugin:
runtime-mode: development
fixedPluginPath:
- "/path/to/plugin-moments"
```

最后重启 Halo 项目即可。

## 主题适配

目前此插件为主题端提供了 `/moments` 路由，模板为 `moments.html`，也提供了 [Finder API](https://docs.halo.run/developer-guide/theme/finder-apis)，可以将瞬间列表渲染到任何地方。

### 模板变量

#### 路由信息
#### 列表页面 /moments

- 模板路径：/templates/moments.html
- 访问路径：/moments?tag={tag} | moments/page/{page}?tag={tag}

#### 参数

tag - 标签名称
**参数**：

#### 变量
- tag：标签名称，用于筛选。

moments
**变量**：

##### 变量类型
- moments：[#UrlContextListResult\<MomentVo>](#urlcontextlistresult-momentvo)
- tags：[#List\<MomentTagVo>](#momenttagvo)

[#UrlContextListResult\<MomentVo>](#urlcontextlistresult-momentvo)

##### 示例
**示例**：

```html
<!-- 渲染标签列表 -->
<ul>
<li th:each="tag : ${tags}">
<a
th:href="|/moments?tag=${tag.name}|"
th:classappend="${#lists.contains(param.tag, tag.name) ? 'active' : ''}"
>
<span th:text="${tag.name}"></span>
<span th:text="${tag.momentCount}"></span>
</a>
</li>
</ul>

<div>
<!-- 渲染瞬间列表 -->
<ul>
<li th:each="moment : ${moments.items}" th:with="content=${moment.spec.content}">
<div th:if="${not #strings.isEmpty(content.html)}" th:utext="${content.html}"></div>
Expand All @@ -105,38 +147,16 @@ moments
</div>
```

#### 变量

tags

##### 变量类型

[#List\<MomentTagVo>](#momenttagvo)

##### 示例

```html
<ul>
<li th:each="tag : ${tags}">
<div th:text="${tag.name}"></div>
</li>
</ul>
```

#### 详情路由
#### 详情页面 /moments/{name}

- 模板路径：/templates/moment.html
- 访问路径：/moments/{name}

#### 变量

moment
**变量**：

##### 变量类型
- moment：[#MomentVo](#momentvo)

[#MomentVo](#momentvo)

##### 示例
**示例**：

```html
<div>
Expand All @@ -151,27 +171,15 @@ moment
</div>
```

### RSS 订阅地址

- 访问路径：/moments/rss.xml

### Finder API

#### listAll()

##### 描述

获取全部瞬间内容。

##### 参数

无

##### 返回值
**返回值类型**：List<[#MomentVo](#momentvo)>

List<[#MomentVo](#momentvo)>

##### 示例
**示例**：

```html
<ul>
Expand All @@ -188,20 +196,16 @@ List<[#MomentVo](#momentvo)>

#### list(page, size)

##### 描述

根据分页参数获取瞬间列表。

##### 参数
**参数**：

1. `page: int` - 分页页码，从 1 开始
2. `size: int` - 分页条数

##### 返回值

[ListResult\<MomentVo>](#listresult-momentvo)
**返回值类型**：[ListResult\<MomentVo>](#listresult-momentvo)

##### 示例
**示例**：

```html
<th:block th:with="moments = ${momentFinder.list(1, 10)}">
Expand All @@ -227,44 +231,45 @@ List<[#MomentVo](#momentvo)>

```json
{
"metadata": {
"name": "string", // 唯一标识
"labels": {
"additionalProp1": "string",
"metadata": {
"name": "string", // 唯一标识
"labels": {
"additionalProp1": "string"
},
"annotations": {
"additionalProp1": "string"
},
"creationTimestamp": "2022-11-20T13:06:38.512Z" // 创建时间
},
"annotations": {
"additionalProp1": "string",
"spec": {
"content": {
"raw": "string", // 原始内容，一般用于编辑器使用
"html": "string", // HTML 内容，用于主题端进行最终渲染的内容
"medium": [
// 媒体内容
{
"type": "#MomentMediaType", // 类型
"url": "string", // 链接
"originType": "string" // 原始类型，例如：image/jpeg
}
]
},
"releaseTime": "string", // 发布时间
"visible": "PUBLIC", // 可见性
"owner": "string", // 所属用户
"tags": ["string"] // 所拥有的标签
},
"creationTimestamp": "2022-11-20T13:06:38.512Z", // 创建时间
},
"spec": {
"content": {
"raw": "string", // 原始内容，一般用于编辑器使用
"html": "string", // HTML 内容，用于主题端进行最终渲染的内容
"medium": [ // 媒体内容
{
"type": "#MomentMediaType", // 类型
"url": "string", // 链接
"originType": "string", // 原始类型，例如：image/jpeg
}
]
"owner": {
"name": "string", // 用户名
"avatar": "string", // 头像
"bio": "string", // 描述
"displayName": "string" // 显示名称
},
"releaseTime": "string", // 发布时间
"visible": "PUBLIC", // 可见性
"owner": "string", // 所属用户
"tags": ["string"], // 所拥有的标签
},
"owner": {
"name": "string", // 用户名
"avatar": "string", // 头像
"bio": "string", // 描述
"displayName": "string", // 显示名称
},
"stats": {
"upvote": 0, // 点赞数
"totalComment": 0, // 评论数
"approvedComment": 0, // 审核通过的评论数
}
"stats": {
"upvote": 0, // 点赞数
"totalComment": 0, // 评论数
"approvedComment": 0 // 审核通过的评论数
}
}
```

Expand All @@ -283,41 +288,41 @@ enum Target {

```json
{
"page": 0, // 当前页码
"size": 0, // 每页条数
"total": 0, // 总条数
"items": "List<#MomentVo>", // 瞬间列表数据
"first": true, // 是否为第一页
"last": true, // 是否为最后一页
"hasNext": true, // 是否有下一页
"hasPrevious": true, // 是否有上一页
"totalPages": 0, // 总页数
"page": 0, // 当前页码
"size": 0, // 每页条数
"total": 0, // 总条数
"items": "List<#MomentVo>", // 瞬间列表数据
"first": true, // 是否为第一页
"last": true, // 是否为最后一页
"hasNext": true, // 是否有下一页
"hasPrevious": true, // 是否有上一页
"totalPages": 0 // 总页数
}
```

#### UrlContextListResult<MomentVo>

```json
{
"page": 0, // 当前页码
"size": 0, // 每页条数
"total": 0, // 总条数
"items": "List<#MomentVo>", // 瞬间列表数据
"first": true, // 是否为第一页
"last": true, // 是否为最后一页
"hasNext": true, // 是否有下一页
"hasPrevious": true, // 是否有上一页
"totalPages": 0, // 总页数
"prevUrl": "string", // 上一页链接
"nextUrl": "string", // 下一页链接
"page": 0, // 当前页码
"size": 0, // 每页条数
"total": 0, // 总条数
"items": "List<#MomentVo>", // 瞬间列表数据
"first": true, // 是否为第一页
"last": true, // 是否为最后一页
"hasNext": true, // 是否有下一页
"hasPrevious": true, // 是否有上一页
"totalPages": 0, // 总页数
"prevUrl": "string", // 上一页链接
"nextUrl": "string" // 下一页链接
}
```

#### MomentTagVo

```json
{
"name": "string", // 标签名称
"momentCount": 0, // 标签所属的 moment 数量
"name": "string", // 标签名称
"momentCount": 0 // 标签所属的 moment 数量
}
```
Binary file added images/plugin-moments-preview.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.