README

例如：创建引用插件

简介

此插件必须能够显示一个用于输入作者名称的字段，以及一个用于插入相关引用的字段。

在本例中，我们将从Thelia模块创建此插件。如果您还不了解Thelia模块的工作原理，我们强烈建议您阅读关于Thelia模块的官方文档。

模块架构

在本例中，我们将使用一个非常特定的架构。当然，您可以自由地按照自己的方式组织模块。

.
├── ...
├── local/modules/ModuleCitation
│   ├── Config/
│   │	├── module.xml
│   │   └── config.xml
│   ├── Hook/
│   │   └── BackHook.php
│   └── templates/
│   │	├── frontOffice/default/blocks/
│   │	│	├── blockCitation.html
│   │   │	└── ...
│   │   └── backOffice/default/
│   │   │	├── src/
│   │   │	│   └── Citation.jsx
│   │   │	├── tsup.config.js
│   │   │	└── index.js
│   ├── package.json
│   └── ModuleCitation.php
└── ...

安装依赖项

npm install react tsup @openstudio/blocks-editor

1 - 创建组件

让我们先创建一个名为 Citation.jsx 的文件，并定义插件的基本数据。

// ./templates/backOffice/default/src/Citation.jsx

const initialData = {
  author: "",
  quote: "",
};

然后，我们将编写一个React组件，该组件允许在Thelia Blocks编辑器中查看插件。

⚠️ 注意：Thelia Blocks插件始终需要两个 props

示例

// ./templates/backOffice/default/src/Citation.jsx

const BlockQuoteComponent = ({ data, onUpdate }) => {
  return (
    <div className="BlockQuote">
      <div className="BlockQuote-field">
        <label htmlFor="author-field">Auteur</label>
        <input
          type="text"
          className="Input__Text"
          id="author-field"
          placeholder="Nom de l'auteur"
          value={data.author}
          onChange={(e) => onUpdate({ ...data, author: e.target.value })}
        />
      </div>
      <div className="BlockQuote-field">
        <label htmlFor="quote-field">Citation</label>
        <textarea
          className="Input__TextArea"
          id="quote-field"
          placeholder="Entrez la citation"
          value={data.quote}
          onChange={(e) => onUpdate({ ...data, quote: e.target.value })}
        />
      </div>
    </div>
  );
};

2 - 合并插件

我们的 citation 插件使用一个 <textarea /> 元素，允许用户插入引用。但是，您可以嵌套某些插件以重用已存在的功能。

在我们的案例中，Text 插件很完美：它已经包含了一个富文本系统和其他可能有用的功能。

让我们看看如何在引用插件中使用它。

// ./templates/backOffice/default/src/Citation.jsx

import { blocks } from "@openstudio/blocks-editor";

const { Text } = blocks; // Récupération du plugin Text dans la liste des plugins

现在我们可以在引用插件中使用 Text。

// ./templates/backOffice/default/src/Citation.jsx

import { generateId } from "@openstudio/blocks-editor";

const BlockQuoteComponent = ({ data, onUpdate }) => {
  return (
    <div className="BlockQuote">
      <div className="BlockQuote-field">
        <label htmlFor="author-field">Auteur</label>
        <input
          type="text"
          className="Input__Text"
          id="author-field"
          placeholder="Nom de l'auteur"
          value={author}
          onChange={(e) => onUpdate({ ...data, author: e.target.value })}
        />
      </div>
      <div className="BlockQuote-field">
        <Text.component
          data={{ value: data.quote }}
          onUpdate={(value) => onUpdate({ ...data, quote: value })}
          id={generateId()}
        />
      </div>
    </div>
  );
};

我们的引用插件现在使用 Text 来工作。

⚠️ 注意：插件必须始终包含一个React组件或继承另一个插件

3 - 插件结构和导出

每个插件都表示为一个对象。它包含所有必要的信息，以确保其正常运行。

示例

// ./templates/backOffice/default/src/Citation.jsx

const blockQuote = {
  type: { id: "blockQuote" },
  component: BlockQuoteComponent,
  initialData,
  icon: Icon,
  title: {
    default: "Quote",
    fr: "Citation",
    en: "Quote",
  },
  description: {
    default: "Display a quote",
    fr: "Affiche une citation",
    en: "Display a quote",
  },
};

export default blockQuote;

4 - 使用Thelia配置插件

4.1 - 将插件添加到Thelia Blocks

现在，您的插件必须添加到Thelia Blocks，以便在创建新块时可用。

函数 "registerPlugin" 负责将插件列表添加到Thelia Blocks。

它由包 @openstudio/blocks-editor 导出

示例

// ./templates/backOffice/default/index.js

import { registerPlugin } from "@openstudio/blocks-editor";
import Citation from "./Citation";

registerPlugin(Citation);

4.2 - 生成捆绑包

⚠️ 以下示例描述了使用tsup的用法，您当然可以使用任何其他捆绑器。

// ./templates/backOffice/default/tsup.config.js

import { defineConfig } from "tsup";

export default defineConfig([
  {
    entry: ["./src/index.js"],
    clean: false,
    dts: {
      entry: ["./src/index.js"],
    },
    sourcemap: true,
    platform: "browser",
    globalName: "MonModule",
    target: "es2020",
  },
]);

4.3 - 创建Smarty模板

<!-- ./templates/backOffice/default/import-plugin.html -->

<script src="{encore_module_asset file='dist/index.global.js' module="ModuleCitation"}"></script>

4.4 - 使用Thelia钩子渲染模板

Thelia Blocks使用两个主要事件来运行

• thelia.blocks.plugins：允许向Thelia Blocks添加插件
• thelia.blocks.plugincss：允许向插件注入CSS

<!-- ./Config/config.xml -->

<hooks>
  <hook id="modulecitation.hook">
    <tag name="hook.event_listener" event="thelia.blocks.plugins" type="back" render="import-plugin.html" />
  </hook>
</hooks>

5 - 创建Smarty渲染

您的插件现在在Thelia Blocks中可用，最后一个步骤是定义HTML结构，当Thelia在您的网站上显示时将生成该结构。

5.1 - 创建您的渲染

首先，在 ./templates/frontOffice/default/blocks 文件夹中创建一个名为 "[id_du_plugin].html" 的文件。

ID 已在插件结构中定义，确保您的文件与 ID 名称完全相同非常重要。否则，Thelia 将无法找到您的插件，并且不会显示任何内容。

示例

<!-- ./templates/frontOffice/default/blocks/blockQuote.html -->

<figure class="tb-{$type["id"]}">
  <blockquote>{$data["quote"]}</blockquote>
  <figcaption>-{$data["author"]}</figcaption>
</figure>

6 - 深入了解

翻译

您还可以翻译您的插件，Thelia Blocks 使用 react-intl 进行翻译。有关 react-intl 的更多详细信息，请参阅 文档。

插件标题和描述的翻译直接在其定义中完成。

具有翻译的插件示例

样式

您还可以根据需要自定义插件样式。事件 thelia.blocks.plugincss 允许在您的插件中注入 CSS。

具有样式的插件示例

TypeScript

Thelia Blocks 的基本插件是用 TypeScript 编写的，但是，您也可以使用传统的 JavaScript 编写它们。