README

EXT:container - 用于创建嵌套内容元素的TYPO3扩展

特性

简单惊人的容器（网格）作为自定义TYPO3内容元素
无默认容器，所有内容都将根据项目需求构建
支持多语言（连接模式或自由模式（混合模式不受支持））
支持工作区
如果已安装EXT:content_defender >= 3.1.0，则支持colPos限制
通过DataProcessor和Fluid模板进行前端渲染

为什么我们创建了另一个"网格"扩展？

在b13，我们一直是gridelements的长期支持者和粉丝，对此我们表示感激，并且我们曾非常愉快地使用了它。

然而，我们过去在与所有评估和合作过的解决方案中都遇到了痛点。以下是我们的原因

我们希望有一个扩展能与多个版本的TYPO3核心版本一起工作，以支持我们公司的TYPO3升级策略。
我们希望在处理colPos字段时克服问题，并且不喜欢任何与TYPO3核心不完全兼容的固定值。
我们希望有一个扩展能够完全测试多语言和工作区功能。
我们希望有一个扩展只做一件事情：EXT:container仅添加创建和渲染容器元素的工具，没有其他功能。没有FlexForms，没有权限处理或自定义渲染。
我们希望每个网格都有自己的内容类型（CType），使其尽可能接近TYPO3核心功能。
我们希望扩展中网格容器元素的配置位于一个单一的位置，以简化自定义容器的创建。
我们希望有一个具有渐进式开发工作流程的扩展：我们在TYPO3 v10 sprint版本中处理新项目，并需要自定义容器元素，不想等到TYPO3 v10 LTS。

安装

通过composer req b13/container安装此扩展或从TYPO3扩展存储库下载，并在您的TYPO3安装的扩展管理器中激活扩展。

安装后，将自定义内容元素添加到您的网站包或主题扩展中（参见“添加您自己的容器元素”）。

添加您自己的容器元素

在Configuration/TCA/Overrides/tt_content.php中将您的自定义容器注册到您的网站包或主题扩展中，作为新内容类型
添加TypoScript和您的Fluid模板以进行前端渲染
在Resources/Public/Icons/<CType>.svg中添加图标

有关自定义容器的简单示例，请参阅EXT:container_example。

容器元素的注册

这是一个创建2列容器的示例。代码片段放入您的网站包或主题扩展中Configuration/TCA/Overrides/文件夹中的一个文件。文件可以具有任何名称，但根据数据库表命名是良好的做法。在这种情况下，这将是一个tt_content.php。

\TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\B13\Container\Tca\Registry::class)->configureContainer(
    (
        new \B13\Container\Tca\ContainerConfiguration(
            'b13-2cols-with-header-container', // CType
            '2 Column Container With Header', // label
            'Some Description of the Container', // description
            [
                [
                    ['name' => 'header', 'colPos' => 200, 'colspan' => 2, 'allowed' => ['CType' => 'header, textmedia']]
                ],
                [
                    ['name' => 'left side', 'colPos' => 201],
                    ['name' => 'right side', 'colPos' => 202]
                ]
            ] // grid configuration
        )
    )
    // set an optional icon configuration
    ->setIcon('EXT:container_example/Resources/Public/Icons/b13-2cols-with-header-container.svg')
);

ContainerConfiguration对象的方法

注释

如果已安装EXT:content_defender >= 3.1.0，您可以在列配置中使用allowed、disallowed和maxitems
容器注册表执行多项操作
- 向TCA选择项添加CType
- 注册您的图标
- 为newContentElement.wizardItems添加PageTSconfig
- 为此CType（sys_language_uid,CType,tx_container_parent,colPos,hidden）设置showitem
- 将配置保存在TCA中，在$GLOBALS['TCA']['tt_content']['containerConfiguration'][<CType>]中以便后续使用
我们提供了一些您可以使用的基本图标，请参阅Resources/Public/Icons
- container-1col
- container-2col
- container-2col-left
- container-2col-right
- container-3col
- container-4col

TypoScript

TypoScript是必要的，用于定义容器在前端的渲染方式。通常您会将它放在您的网站包或主题扩展中，靠近定义其他关于您的内容元素的地方。templateRootPaths必须根据您的网站包或主题扩展中html文件的路径进行修改。

// default/general configuration (will add 'children_<colPos>' variable to processedData for each colPos in container
tt_content.b13-2cols-with-header-container < lib.contentElement
tt_content.b13-2cols-with-header-container {
    templateName = 2ColsWithHeader
    templateRootPaths {
        10 = EXT:container_example/Resources/Private/Templates
    }
    dataProcessing {
        100 = B13\Container\DataProcessing\ContainerProcessor
    }
}

// if needed you can use ContainerProcessor with explicitly set colPos/variable values
tt_content.b13-2cols-with-header-container < lib.contentElement
tt_content.b13-2cols-with-header-container {
    templateName = 2ColsWithHeader
    templateRootPaths {
        10 = EXT:container_example/Resources/Private/Templates
    }
    dataProcessing {
        200 = B13\Container\DataProcessing\ContainerProcessor
        200 {
            colPos = 200
            as = children_200
        }
        201 = B13\Container\DataProcessing\ContainerProcessor
        201 {
            colPos = 201
            as = children_201
        }
    }
}

数据处理选项

模板

html模板文件应放在您在TypoScript中定义的文件夹中（见templateRootPaths）。文件名必须与TypoScript中定义的templateName完全一致，在本例中为2ColsWithHeader.html。文件名区分大小写！

<f:for each="{children_200}" as="record">
    {record.header} <br>
    <f:format.raw>
        {record.renderedContent}
    </f:format.raw>
</f:for>

<f:for each="{children_201}" as="record">
    {record.header} <br>
    <f:format.raw>
        {record.renderedContent}
    </f:format.raw>
</f:for>

如果显式定义了列位置，则使用上面的示例中设置的{children_200|201}

概念

完整的注册通过一次PHP调用TCA注册表完成
在TYPO3后端页面模块中，容器渲染的方式类似于一个页面本身（见View/ContainerLayoutView）
对于后端剪贴板和拖放，使用<tx_container_parent>_<colPos>在包装CE-div元素的data-colpos属性中（而不是在PageLayoutView中仅使用colPos）
<tx_container_parent>_<colPos>参数在DataHandler钩子中解析为tx_container_parent和colPos值
在翻译容器时，所有子元素也会被翻译（子元素在翻译对话框中并未明确列出）
复制或移动容器的子元素时，也会复制或移动翻译
自定义定义使用自定义的colPos值，因此网站所有者可以构建自己的元素，没有固定的colPos，因此不会与现有解决方案冲突
每个容器类型只是其自己的CType的定义

CLI命令

有几个CLI命令可以检查/修复容器及其子元素的完整性。

# Check the sorting of container children
vendor/bin/typo3 container:sorting

# Fix the sorting of container children on page 123
vendor/bin/typo3 container:sorting --apply 123

# Check the sorting of records in page colPos
vendor/bin/typo3 container:sorting-in-page

# ??
bin/typo3 container:fixLanguageMode
bin/typo3 container:fixContainerParentForConnectedMode
bin/typo3 container:deleteChildrenWithWrongPid
bin/typo3 container:deleteChildrenWithNonExistingParent

待办事项

完整性证明
列出模块操作

扩展测试和编码规范

您可以运行我们的测试套件来测试此扩展

运行composer install
运行Build/Scripts/runTests.sh -s unit
运行Build/Scripts/runTests.sh -s functional
运行Build/Scripts/runTests.sh -s acceptance

有关如何在本地上运行测试的说明，请参阅Tests/README.md（类似于github-actions运行的测试）。

为了确保满足编码规范

运行.Build/bin/phpstan analyse -c Build/phpstan10.neon
运行.Build/bin/php-cs-fixer fix --config=Build/php-cs-fixer.php --dry-run --stop-on-violation --using-cache=no

致谢

此扩展由Achim Fritz于2020年创建，用于b13 GmbH, Stuttgart。

在我们的b13.com容器系列博客中找到此扩展的示例、用例和最佳实践。

在此处找到我们开发的更多TYPO3扩展，这些扩展有助于我们在客户项目中提供价值。作为我们工作方式的一部分，我们专注于测试和最佳实践，以确保我们所有代码的长期性能、可靠性和效果。

b13 / container

维护者

详情