README

为您的TYPO3项目提供组件库功能

关于

此TYPO3扩展

鼓励并支持在您的TYPO3项目中开发独立、可重用的功能模块和设计模块（"组件"），并且
通过JSON API公开这些组件，以便 组件或模式库、测试和风格指南工具 如 Fractal 可以提取和渲染您的组件，独立于您的TYPO3前端。

使用

安装

将扩展安装到您的 Composer模式TYPO3 安装中

cd /path/to/site/root
composer require tollwerk/tw-componentlibrary

或者，下载最新的源码包并将其内容解压到 typo3conf/ext/tw_componentlibrary。

通过TYPO3扩展管理器启用扩展。

组件类型

该扩展区分5种主要的组件类型

TypoScript组件：需要渲染的对象定义的 TypoScript 路径（例如，lib.menu，定义为 HMENU）。
Fluid模板组件：需要 Fluid模板文件（例如，Extbase / Fluid部分或独立Fluid模板）以及可选的渲染参数/变量集。
Extbase插件组件：需要 Extbase控制器、要调用的控制器操作以及传递给控制器操作的参数列表（如果有的话）。
内容组件：方便地将现有的TYPO3内容元素作为组件渲染。与默认内容和自定义内容元素都兼容。
表单组件：挂钩到 TYPO3表单框架并将标准表单元素和自定义表单元素视为单独的组件。

该扩展 不对您的TypoScript、Fluid模板或目录布局提出任何要求，除了每个组件都必须可以单独访问。也就是说，您不能仅将渲染的Fluid模板的一部分公开为组件。在这种情况下，您必须将所需的部件作为独立的部分文件外包出去。

声明组件

您可以手动声明组件（下面将描述）或使用命令行组件启动器。

创建并安装一个空的TYPO3扩展，该扩展将包含您的组件定义。或者，选择一个您可以写入的现有扩展。可以拥有多个这样的 组件提供者扩展。如果您无论如何都在使用和维护自定义扩展，我建议您根据每个扩展提供组件。
在提供者扩展的根目录内创建一个 Components 目录。如果您正在以 Composer 模式运行 TYPO3，请确保此目录正确映射到 Component 命名空间。您可能需要将以下内容添加到您的主 composer.json 文件中（将供应商名称、扩展密钥和路径替换为适当的本地值）
```
{
    "autoload": {
        "psr-4": {
            "Vendor\\ExtKey\\Component\\": "web/typo3conf/ext/ext_key/Components/"
        }
    }
}
```
如果您有很多组件，建议按层次结构组织它们。在您的 Components 文件夹下创建合适的目录布局以反映这种层次结构。使用没有空格、下划线和特殊字符的 UpperCamelCase 目录名称。您的目录布局可能如下所示
```
ext_key
`-- Components
    |-- Composite
    |   `-- Form
    `-- Generic
        |-- Form
        `-- Typography
```
通过在目录布局中适当位置创建 PHP 类文件来开始创建 组件声明。每个文件必须声明一个扩展以下之一的主组件类型基类的 一个类（见下文）。文件和类名必须相同，应使用 UpperCamelCase，并且必须以后缀 …Component 结尾（文件名分别为 …Component.php）。…Component 前的部分将被外部工具用作组件。除了组件的基本版本外，您还可以通过在文件和类名中添加下划线和后缀来提供该组件的变体。系统如 Fractal 可以使用此功能来分组显示组件变体
```
ext_key
`-- Components
    `-- Generic
        `-- Form
            |-- ButtonComponent.php
            |-- Button_IconLeftComponent.php
            |-- Button_IconRightComponent.php
            |-- Button_LinkComponent.php
            |-- Button_LinkIconLeftComponent.php
            `-- Button_LinkIconRightComponent.php
```
使用组件声明的 configure() 方法指定各个组件属性。虽然每种组件类型都带来了一小套特定的属性（见下文），但大多数说明是对所有组件类型通用的。

TypoScript 组件

使用 setTypoScriptKey() 方法指定渲染组件输出的 TypoScript 对象。键将对 $page 属性指定的页面 ID 进行评估（见通用属性）。

<?php

namespace Vendor\ExtKey\Component;

use Tollwerk\TwComponentlibrary\Component\TypoScriptComponent;

/**
 * Example TypoScript component
 */
class ExampleTypoScriptComponent extends TypoScriptComponent
{
    /**
     * Configure the component
     */
    protected function configure()
    {
        $this->setTypoScriptKey('lib.example');
    }
}

Fluid 模板组件

使用 setTemplate() 方法指定渲染组件输出的 Fluid 模板文件。使用 setParameter() 方法指定渲染参数（与 Extbase 控制器操作中的 $this->view->assign('param', 'value') 类似）。

<?php

namespace Vendor\ExtKey\Component;

use Tollwerk\TwComponentlibrary\Component\FluidTemplateComponent;

/**
 * Example Fluid template component
 */
class ExampleFluidTemplateComponent extends FluidTemplateComponent
{
    /**
     * Configure the component
     */
    protected function configure()
    {
        $this->setTemplate('EXT:ext_kex/Resources/Private/Partials/Component.html');
        $this->setParameter('param', 'value');
    }
}

出于方便起见，Fluid 模板组件可以读取外部 JSON 文件来设置参数。JSON 参数文件必须以相关组件文件命名，并位于同一目录下

|-- ButtonComponent.json
`-- ButtonComponent.php

JSON 文件内的键值对将被用作 setParameter() 方法的输入。

Extbase 插件组件

要配置 Extbase 插件组件，请使用 setExtbaseConfiguration() 方法指定插件名称、控制器类名称和要调用的控制器操作。输出将使用与控制器操作关联的 Fluid 模板进行渲染。您可以通过 setControllerActionArgument() 指定操作参数，并通过 setControllerSettings() 模拟控制器设置。

<?php

namespace Vendor\ExtKey\Component;

use Tollwerk\TwComponentlibrary\Component\ExtbaseComponent;

/**
 * Example Extbase plugin component
 */
class ExampleExtbaseComponent extends ExtbaseComponent
{
    /**
     * Configure the component
     */
    protected function configure()
    {
        $this->setExtbaseConfiguration('PluginName', MyCustomController::class, 'action');
        $this->setControllerActionArgument('param', [1, 2, 3]);
        
        $overrideExistingSettings = true;
        $this->setControllerSettings(['category' => 1], $overrideExistingSettings);
    }
}

内容组件

使用 setContentRecordId() 方法指定要作为组件渲染的现有内容元素（tt_content 表）的 UID（请确保内容元素是可访问的/没有通过任何方式隐藏）。

<?php

namespace Vendor\ExtKey\Component;

use Tollwerk\TwComponentlibrary\Component\ContentComponent;

/**
 * Example content component
 */
class ExampleContentComponent extends ContentComponent
{
    /**
     * Configure the component
     */
    protected function configure()
    {
        $this->setContentRecordId(123);
    }
}

表单组件

在您的组件定义中，您必须使用 createElement() 方法实例化一个可渲染的表单元素（TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable）。这基本上与您通过表单框架的 Page::createElement() 方法在 API 表单组合期间获得的相同对象。您可以使用其原生方法进一步配置表单元素（就像在表单工厂类中做的那样）。

为了为您的元素模拟表单验证错误，只需调用 addElementError($message)（元素必须在添加错误之前实例化）。您可以注册多个错误。

建议使用 setTemplate() 注册表单字段的 Fluid 模板，以便在组件库中更好地显示，但这不是强制性的。

<?php

namespace Vendor\ExtKey\Component;

use Tollwerk\TwComponentlibrary\Component\FormComponent;

/**
 * Example form component
 */
class ExampleTextComponent extends FormComponent
{
    /**
     * Configure the component
     */
    protected function configure()
    {
        $this->setTemplate('EXT:example/Resources/Private/Partials/Form/Text.html');
        
        $element = $this->createElement('Text', 'name');
        $element->setProperty(
            'fluidAdditionalAttributes',
            [
                'placeholder' => 'John Doe',
            ]
        );
        
        $this->addError('Please enter a name');
    }
}

常见属性

有许多组件属性和方法对所有组件类型都是通用的。其中一些通过 TypoScript 常量控制，其他则通过覆盖组件类属性或调用共享配置方法来控制。

TypoScript 常量

使用 TypoScript 常量可以全局配置外部系统渲染您的组件时包围的 HTML 文档。您可以通过这种方式添加基础文件、网络字体和库（例如 global.css、jQuery 等）。所有资源都可以引用绝对路径（以 http:// 或 https:// 开头）、相对路径（例如 /fileadmin/css/...）或使用 TYPO3 扩展前缀（例如 EXT:ext_key/Resources/...）。

TypoScript-Namensraum: plugin.tx_twcomponentlibrary.settings

组件属性

您可以在组件类中覆盖几个 受保护的 对象属性以改变默认行为。

¹ \TYPO3\CMS\Extbase\Mvc\Web\Request
² \Tollwerk\TwComponentlibrary\Component\Preview\TemplateInterface
³ \Tollwerk\TwComponentlibrary\Component\Preview\FluidTemplate

示例用法

<?php

namespace Vendor\ExtKey\Component;

use Tollwerk\TwComponentlibrary\Component\FluidTemplateComponent;

/**
 * Example Fluid template component
 */
class ExampleFluidTemplateComponent extends FluidTemplateComponent
{
    /**
     * Component status
     *
     * @var int
     */
    protected $status = self::STATUS_READY;
    
    /**
     * Label
     *
     * @var string
     */
    protected $label = 'Button with icon';
    
    /**
     * Configure the component
     */
    protected function configure()
    {
        $this->setTemplate('EXT:ext_kex/Resources/Private/Partials/Button/Icon.html');
    }
}

配置方法

使用以下方法进一步配置您的组件。

<?php

namespace Tollwerk\TwComponentlibrary\Component;

use \Tollwerk\TwComponentlibrary\Component\ComponentInterface;

/**
 * Abstract component
 */
abstract class AbstractComponent implements ComponentInterface
{
    /**
     * Add a notice
     * 
     * Fractal displays the notice in the "Notes" tab (only available for the default component variant)
     *
     * @param string $notice Notice
     */
    protected function addNotice($notice) {}
    
    /**
     * Set a custom preview template
     * 
     * Overrides the default preview template facilitating the `stylesheets`, `headerScript` and `footerScript` TypoScript constants
     *
     * @param TemplateInterface|string|null $preview Preview template
     */
    protected function setPreview($preview) {}
}

预览模板

默认情况下，内置的 FluidTemplate 用于为外部系统渲染组件。只要您实现了 TemplateInterface，您就可以使用自定义模板。默认的 FluidTemplate 支持一些配置方法

<?php

namespace Tollwerk\TwComponentlibrary\Component\Preview;

use TYPO3\CMS\Core\Utility\GeneralUtility;

/**
 * Basic preview template
 *
 * @package Tollwerk\TwComponentlibrary
 * @subpackage Tollwerk\TwComponentlibrary\Component
 */
class FluidTemplate implements TemplateInterface
{
    /**
     * Add a CSS stylesheet
     * 
     * Will be added in the `<head>` section of the preview template
     *
     * @param string $url CSS stylesheet URL
     */
    public function addStylesheet($url){}

    /**
     * Add a header JavaScript
     * 
     * Will be added in the `<head>` section of the preview template
     *
     * @param string $url Header JavaScript URL
     */
    public function addHeaderScript($url){}

    /**
     * Add a header inclusion resource
     * 
     * Path to a file to be included in the in the `<head>` section of
     * the preview template. Make sure to wrap the content e.g. in a    
     * `<script>` or `<style>` element. 
     *
     * @param string $path Header inclusion path
     */
    public function addHeaderInclude($path) {}

    /**
     * Add a footer JavaScript
     * 
     * Will be added just before the closing `</body>` element of the preview template
     *
     * @param string $path Footer JavaScript URL
     */
    public function addFooterScript($url) {}

    /**
     * Add a footer inclusion resource
     * 
     * Path to a file to be included in the in the `<head>` section of
     * the preview template. Make sure to wrap the content e.g. in a    
     * `<script>` or `<style>` element.
     *
     * @param string $path Footer inclusion path
     */
    public function addFooterInclude($path) {}
}

示例用法

<?php

namespace Vendor\ExtKey\Component;

use Tollwerk\TwComponentlibrary\Component\FluidTemplateComponent;

/**
 * Example Fluid template component
 */
class ExampleFluidTemplateComponent extends FluidTemplateComponent
{
    /**
     * Configure the component
     */
    protected function configure()
    {
        $this->setTemplate('EXT:ext_kex/Resources/Private/Partials/Component.html');
        
        // Configure the preview template
        $this->preview->addHeaderInclude('fileadmin/js/icons-loader.html');
        $this->preview->addStylesheet('EXT:ext_key/Resources/Public/Css/example.min.css');
    }
}

文档

您可以通过两种方式为组件添加文档

通过在组件的 configure() 方法内部使用 addNotice($str)。
通过创建一个以组件命名的 文档目录（不带变体后缀）并将文档文件放入其中。当组件被提取时，它将首先检查该目录中是否存在名为 index.md、readme.md 或 <component>.md 的文件。
- 如果存在，该文件将被用作主要文档。
- 如果没有这样的文档索引，将生成一个简单的 Markdown 列表，列出目录中的所有文件。有效的图像文件将作为图像嵌入，否则将显示链接的文件名。
示例
```
|-- Button
|   |-- index.md
|   `-- screenshot.jpg
`-- ButtonComponent.php
```
在组件提取期间，文档（包括图像）中的链接文件将被重写为其相对于 TYPO3 主目录的根路径。

目录配置

从版本 0.3.2 开始，您可以将特定目录的配置值添加到组件目录布局中。当导出组件时，其父目录的值也将被导出。通过创建一个包含任意 JSON 数据结构的文件（例如）来向目录添加配置值 local.json。

{
  "dirsort": 4,
  "label": 'Icons & images'
}

这些值的使用取决于消耗应用程序的具体目的。例如，TYPO3-Fractal-bridge 使用 dirsort 值来按非字母顺序排序目录，并使用 label 为无法通过真实文件系统目录名称实现的组件文件夹名称。

命令行组件启动器

扩展提供了一个命令行组件启动器，可以轻松地搭建新组件。它作为一个 extbase CLI 命令实现。

php vendor/bin/typo3 component:create Test/Button fluid tw_tollwerk Tollwerk

该命令需要 4 个参数（以下顺序；您也可以使用明确的参数名称输入）

--name：组件在提供者扩展的Components目录中的路径和名称。
--type：组件类型，必须是以下之一：fluid、typoscript、extbase、content或form
--extension：提供者扩展键
--vendor：提供者扩展供应商名称

上述命令将在tw_tollwerk扩展内部启动名为Button的Fluid组件。

Components/
`-- Test
    `-- ButtonComponent.php

如果您主要向特定的提供者扩展添加组件，可以通过定义一个默认提供者扩展及其相应的默认供应商名称来简化流程。为此，请进入扩展管理器中的扩展配置，并设置这两个设置。

在调用CLI命令时，可以省略--extension和--vendor参数。

php vendor/bin/typo3 component:create Test/Button fluid

提取组件

该扩展添加了一个Extbase CLI命令，允许您在命令行中以JSON格式发现声明的组件。

vendor/bin/typo3 component:discover

示例结果

[
    {
         "status": "wip",
         "name": "My Widget",
         "variant": null,
         "label": "Alternative component label",
         "class": "Vendor\\ExtKey\\Component\\MyWidgetComponent",
         "type": "fluid",
         "valid": true,
         "parameters": [],
         "config": "EXT:ext_key/Resources/Private/Partials/Widget.html",
         "template": "<f:link.action action=\"...\">...</f:link.action>",
         "extension": "t3s",
         "preview": "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"UTF-8\"><title>{{ _target.label }} \u2014 Preview Layout</title></head><body>{{{ yield }}}</body></html>",
         "request": {
             "method": "GET",
             "arguments": {
                 "L": 0,
                 "id": 1
             }
         },
         "path": [
             "Demo"
         ]
     }
 ]

根据您的需要以任何合理的方式使用公开的JSON数据。例如，Fractal-TYPO3桥接器可以从中构建一个可探索的组件库。

重要提示：从版本1.0开始，只有当扩展的TypoScript设置中包含值为1的features.exportComponents键时，扩展声明的组件才会被导出。这通常位于全局TypoScript配置中的plugin.tx_myext，其中tx_myext由前缀tx_和您的扩展键（无下划线）构成。

plugin.tx_myext {
    features {
        exportComponents = 1
    }
}

您可以通过扩展常量来配置此功能。组件库扩展附带了一个可用于此目的的语言标签（在constants.typoscript中）。

# cat=plugin.tx_myext/enable/a; type=boolean; label=LLL:EXT:tw_componentlibrary/Resources/Private/Language/locallang_core.xlf:enable.export
exportComponents =

渲染组件

该扩展引入了新的type参数值2400，用于调用TYPO3作为单个组件的渲染引擎。请求

http://example.com/?type=2400&tx_twcomponentlibrary_component%5Bcomponent%5D=Vendor%5CExtKey%5CComponent%5CMyWidgetComponent

将仅渲染组件\Vendor\ExtKey\Component\MyWidgetComponent，并返回生成的源代码，而不包含周围的页面级别HTML。

组件依赖图

该扩展引入了新的type参数值2401，用于动态渲染组件依赖图。请求

http://example.com/?type=2401&tx_twcomponentlibrary_component%5Bcomponent%5D=Vendor%5CExtKey%5CComponent%5CMyWidgetComponent

将创建一个如上所示的单一组件依赖图

要创建所有已注册组件的概述图，只需省略组件参数。URL

http://example.com/?type=2401

将创建一个如图所示的图

您可以使用这些图用于文档目的或在Fractal组件库工具中显示它们。

实用工具

SvgIconUtility

包含的类\Tollwerk\TwComponentlibrary\Utility\SvgIconUtility可以帮助您在后台表单和自定义应用程序中列出SVG图形。使用TypoScript常量plugin.tx_twcomponentlibrary.settings.iconDirectories提供以逗号分隔的目录列表。然后，以下两个方法将找到并返回这些目录中的所有*.svg文件。

`SvgIconUtility::getIcons(int $id = 1, int $typeNum = 0): array`

返回一个数组，其中SVG图形的文件基本名称作为值，绝对文件路径作为键。可选地提供页面ID和类型，用于确定图标目录。

`SvgIconUtility::getIconTcaSelectItems(int $id = 1, int $typeNum = 0): array`

类似于getIcons()，但返回的图形已准备好用于TCA select字段。

TYPO3后端集成

该扩展提供了一个简单的集成，您可以在TYPO3后端更新组件库。到目前为止，仅支持Fractal组件库。要启用Fractal支持，请按照以下简单步骤操作

从扩展管理器进入扩展配置，并启用使用Fractal
提供能够运行更新和重启组件库所需步骤的shell脚本的绝对路径。您可以在Resources/Private/Script中找到一个示例文件。

使用shell脚本更新Fractal很简单：假设您正在使用TYPO3 Fractal桥，只需在Fractal实例目录中执行cd命令并运行fractal update-typo3。是否需要重新初始化Fractal取决于您的具体配置。
确保shell脚本对您的Web服务器运行的用户是可执行的，并在脚本中需要的地方使用sudo（可能需要配置适当的sudo权限，这超出了本文档的范围）。请小心——如果shell脚本制作不当，可能会损害您的系统！
一旦您启用了组件库的支持，并将shell脚本放置就绪，您应该会在缓存菜单下拉菜单中找到一个额外的菜单项。
如果操作正确，您现在可以轻松地从TYPO3后端更新和重新初始化组件库。根据您系统中组件的数量，更新过程可能需要一些时间。

贡献

发现了错误或有功能请求？请先查看已知问题，如有必要，请创建一个新的问题。有关详细信息，请参阅贡献指南和行为准则。

安全

如果您发现任何与安全相关的问题，请通过电子邮件joschi@kuphal.net联系我们，而不是使用问题跟踪器。

tollwerk / tw-componentlibrary

维护者

详情