TYPO3扩展tt_content新增FAL图片字段并实现前端渲染

需要为tt_content表扩展一个所有内容元素都可配置的图片字段，已完成的实现代码如下：

ext_tables.sql 数据库定义 #

CREATE TABLE tt_content (
   tx_layout_background_image int(11) unsigned DEFAULT '0' NOT NULL,
);

TypoScript 配置 #

page.10 = FLUIDTEMPLATE
page.10 {
  templateName = TEXT
  templateName.stdWrap.cObject = CASE
  templateName.stdWrap.cObject {
    key.data = pagelayout
    pagets__kubus_layout = TEXT
    pagets__kubus_layout.value = Default
    default = TEXT
    default.value = Default
  }
  templateRootPaths {
    0 = {$resDir}/Private/Templates/Page/
  }
  partialRootPaths {
    0 = {$resDir}/Private/Partials/Page/
  }
  layoutRootPaths {
    0 = {$resDir}/Private/Layouts/Page/
  }
  dataProcessing {
    20 = TYPO3\CMS\Frontend\DataProcessing\FilesProcessor
    20 {
      references {
        table = tt_content
        uid.field = uid
        fieldName = tx_layout_background_image
      }
      as = images
    }
  }
}

Overrides/tt_content.php TCA配置 #

<?php

$temporaryColumn = array(
    'tx_layout_background_image' => [
        'label' => 'BG Image',
        'config' => \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::getFileFieldTCAConfig(
            'tx_layout_background_image',
            [
                'appearance' => [
                    'createNewRelationLinkTitle' => 'LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:images.addFileReference'
                ],
                'overrideChildTca' => [
                    'columns' => [
                        'crop' => [
                            'description' => 'field description',
                        ],
                    ],
                    'types' => [
                        \TYPO3\CMS\Core\Resource\File::FILETYPE_IMAGE => [
                            'showitem' => '
                               --palette--;;imageoverlayPalette,
                               --palette--;;filePalette'
                        ],
                    ],
                ],
            ],
            $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']
        ),
    ],
);

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTCAcolumns(
    'tt_content',
    $temporaryColumn
);

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addFieldsToPalette(
    'tt_content',
    'layout',
    'tx_layout_background_image',
    'after:layout'
);

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addToAllTCAtypes(
    'tt_content',
    '--div--;Layout,
    --palette--;;layout',
    '',
    ''
);

前端渲染时数据数组中仅能获取到字段关联计数值，无法拿到完整图片对象：

data.tx_layout_background_image => 1 (integer)

配置treatasreference参数后问题依然存在。 #

故障核心原因是FilesProcessor配置层级错误：放在页面级FLUIDTEMPLATE下的文件处理器，仅会处理当前pages表页面对象的字段关联，不会读取tt_content内容元素的文件引用，因此只能拿到字段存储的关联数量，无法拉取实际文件数据。
正确的配置方式是给内容元素通用渲染对象lib.contentElement添加对应的文件处理器，内容元素渲染时会自动加载该处理器，解析对应字段的文件关联，配置如下：

lib.contentElement {
    dataProcessing.99 = TYPO3\CMS\Frontend\DataProcessing\FilesProcessor
    dataProcessing.99 {
        as = backgroundImages
        references.fieldName = tx_layout_background_image
        references.table = tt_content
   }
}

添加上述配置后，模板中可直接通过{backgroundImages}变量获取完整的图片文件对象数组，正常调用渲染即可。

补充：如果要在页面模板层级通过dataProcessing处理内容元素的文件字段，必须保证处理器运行时的上下文是对应内容元素的记录，而非页面根对象记录，否则uid匹配错误就无法拉取到正确的关联文件。

内容的提问来源于stack exchange，提问作者180690