FlexForms

Example use cases

The bootstrap_package uses FlexForms to configure rendering options, e.g. a transition interval and transition type (slide, fade) for the carousel content element.

Another extensions that utilize FlexForms and can be used as example is:

• georgringer/news

How it works

1. In the extension, a configuration schema is defined and attached to one or more content elements or plugins.
2. When the CE or plugin is added to a page, it can be configured as defined by the configuration schema.
3. The configuration for this content element is automatically saved to tt_content.pi_flexform.
4. The extension can read current configuration and act according to the configuration.

Steps to perform (extension developer)

1. Create configuration schema in T3DataStructure format (XML)

   Example:

   EXT:examples/Configuration/Flexforms/PluginHaikuList.xml

   <T3DataStructure>
       <sheets>
           <sDEF>
               <ROOT>
                   <sheetTitle>
                       LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:examples.pi_flexform.sheetGeneral
                   </sheetTitle>
                   <type>array</type>
                   <el>
                       <settings.singlePid>
                           <label>
                               LLL:EXT:examples/Resources/Private/Language/PluginHaiku/locallang_db.xlf:singlePageUid
                           </label>
                           <config>
                               <type>group</type>
                               <allowed>pages</allowed>
                               <maxitems>1</maxitems>
                               <minitems>0</minitems>
                               <size>1</size>
                               <suggestOptions>
                                   <default>
                                       <additionalSearchFields>nav_title, alias, url</additionalSearchFields>
                                       <addWhere>AND pages.doktype = 1</addWhere>
                                   </default>
                               </suggestOptions>
                           </config>
                       </settings.singlePid>
                   </el>
               </ROOT>
           </sDEF>
       </sheets>
   </T3DataStructure>

   Copied!

2. The configuration schema is attached to one or more plugins in the folder Configuration/TCA/Overrides of an extension.

   Example for the FlexForm registration of a basic plugin:

   EXT:examples/Configuration/TCA/Overrides/tt_content_plugin_haiku_list.php

   <?php
   
   /*
    * This file is part of the TYPO3 CMS project. [...]
    */
   
   use TYPO3\CMS\Core\Schema\Struct\SelectItem;
   use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
   
   /*
    * This file is part of the TYPO3 CMS project. [...]
    */
   
   defined('TYPO3') or die();
   
   $pluginSignature = 'examples_haiku_list';
   
   ExtensionManagementUtility::addPlugin(
       new SelectItem(
           'select',
           'LLL:EXT:examples/Resources/Private/Language/PluginHaiku/locallang_db.xlf:list.title',
           $pluginSignature,
           'tx_examples-haiku',
           'plugins',
           'LLL:EXT:examples/Resources/Private/Language/PluginHaiku/locallang_db.xlf:list.description',
       ),
       'CType',
       'examples',
   );
   
   ExtensionManagementUtility::addToAllTCAtypes(
       'tt_content',
       '--div--;Configuration,pi_flexform,',
       $pluginSignature,
       'after:subheader',
   );
   
   ExtensionManagementUtility::addPiFlexFormValue(
       '*',
       'FILE:EXT:examples/Configuration/Flexforms/PluginHaikuList.xml',
       $pluginSignature,
   );

   Copied!

   New in version 12.0

   The method ExtensionUtility::registerPlugin() returns the plugin signature.

   When registering Extbase plugins you can use the return value of ExtensionUtility::registerPlugin() to figure out the plugin signature to use:

   EXT:blog_example/Configuration/TCA/Overrides/tt_content.php (Excerpt)

   $pluginSignature = ExtensionUtility::registerPlugin(
       'blog_example',
       'Pi1',
       'A Blog Example',
   );
   $GLOBALS['TCA']['tt_content']['types']['list']['subtypes_addlist'][$pluginSignature]
       = 'pi_flexform';
   ExtensionManagementUtility::addPiFlexFormValue(
       $pluginSignature,
       'FILE:EXT:blog_example/Configuration/FlexForms/PluginSettings.xml'
   );

   Copied!

   If you are using a content element with a custom CType (recommend, both with and without Extbase), the example looks like this:

   EXT:my_extension/Configuration/TCA/Overrides/tt_content.php

   \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPiFlexFormValue(
       '*',
       // FlexForm configuration schema file
       'FILE:EXT:example/Configuration/FlexForms/Registration.xml',
       // ctype
       'accordion'
   );

   Copied!

   Finally, according to "Configuration of the displayed order of fields in FormEngine and their tab alignment." the field containing the FlexForm still needs to be added to the showitem directive. The following example shows line from the accordion element of the Bootstrap Package.

   EXT:your_extension/Configuration/TCA/Overrides/tt_content.php

   // Configure element type
   $GLOBALS['TCA']['tt_content']['types']['accordion'] = array_replace_recursive(
       $GLOBALS['TCA']['tt_content']['types']['accordion'],
       [
           'showitem' => '
               --div--;General,
               --palette--;General;general,
               --palette--;Headers;headers,
               tx_bootstrappackage_accordion_item,
               --div--;Options,
               pi_flexform'
       ]
   );

   Copied!

3. Access the settings in your extension:

   The settings can be read using one of the methods described below, e.g. from an Extbase controller action, from a PHP function (without using the Extbase framework), from TypoScript or from within a Fluid template.

More examples

The definition of the data types and parameters used complies to the column types defined by TCA.

The settings must be added within the <el> element in the FlexForm configuration schema file.

<settings.orderBy>
    <label>
        LLL:EXT:example/Resources/Private/Language/Backend.xlf:settings.registration.orderBy
    </label>
    <config>
        <type>select</type>
        <renderType>selectSingle</renderType>
        <items>
            <numIndex index="0">
                <label>
                    LLL:EXT:example/Resources/Private/Language/Backend.xlf:settings.registration.orderBy.crdate
                </label>
                <value>crdate</value>
            </numIndex>
            <numIndex index="1">
                <label>
                    LLL:EXT:example/Resources/Private/Language/Backend.xlf:settings.registration.orderBy.title
                </label>
                <value>title</value>
            </numIndex>
        </items>
    </config>
</settings.orderBy>

Populate a select field with a PHP Function (itemsProcFunc)

<settings.orderBy>
    <label>
        LLL:EXT:example/Resources/Private/Language/Backend.xlf:settings.registration.orderBy
    </label>
    <config>
        <type>select</type>
        <itemsProcFunc>MyVendor\Example\Backend\ItemsProcFunc->user_orderBy
        </itemsProcFunc>
        <renderType>selectSingle</renderType>
        <items>
            <!-- empty by default -->
        </items>
    </config>
</settings.orderBy>

Copied!

The function user_orderBy populates the select field in Backend/ItemsProcFunc.php:

class ItemsProcFunc
{
     /**
     * Modifies the select box of orderBy-options.
     *
     * @param array &$config configuration array
     */
    public function user_orderBy(array &$config)
    {
        // simple and stupid example
        // change this to dynamically populate the list!
        $config['items'] = [
            // label, value
            ['Timestamp', 'timestamp'],
            ['Title', 'title']
        ];
    }

    // ...
}

Copied!

How this looks when configuring the plugin:

See also

• - in TCA reference.

<config>
    <type>select</type>
</config>
<!-- Hide field if value of neighbour field "settings.orderBy" on same sheet is not "title" -->
<displayCond>FIELD:settings.orderBy:!=:title</displayCond>

<onChange>reload</onChange>
<config>
    <!-- ... -->
</config>

$includeCategories = (bool) ($this->settings['includeCategories'] ?? false);

use TYPO3\CMS\Core\Service\FlexFormService;
use TYPO3\CMS\Core\Utility\GeneralUtility;

final class NonExtbaseController
{

    // Inject FlexFormService
    public function __construct(
        private readonly FlexFormService $flexFormService,
    ) {
    }

    // ...

    private function loadFlexForm($flexFormString): array
    {
        return $this->flexFormService
            ->convertFlexFormContentToArray($flexFormString);
    }
}

 var_export(
     $this->flexFormService->convertFlexFormContentToArray($flexFormString)
 );

/* Output:
[
    'settings' => [
        'singlePid' => 25,
        'listPid' => 380,
    ],
]
*/

var_export(GeneralUtility::xml2array($flexFormString)));

/* Output:
[
    'data' =>
        [
            'sDEF' =>
                [
                    'lDEF' =>
                        [
                            'settings.singlePid' =>['vDEF' => '4',],
                            'settings.listPid' =>['vDEF' => '',],
                        ],
                ],
        ],
];
*/

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

use TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools;
use TYPO3\CMS\Core\Utility\GeneralUtility;

class _FlexformModificationService
{
    public function __construct(
        protected readonly FlexFormTools $flexFormTools,
    ) {}

    public function modifyFlexForm(string $flexFormString): string
    {
        $flexFormArray = GeneralUtility::xml2array($flexFormString);
        $changedFlexFormArray = $this->doSomething($flexFormArray);

        // Attention: flexArray2Xml is internal and subject to
        // be changed without notice. Use at your own risk!
        return $this->flexFormTools->flexArray2Xml($changedFlexFormArray, addPrologue: true);
    }

    private function doSomething(array $flexFormArray): array
    {
        // do something to the array
        return $flexFormArray;
    }
}

lib.flexformContent = CONTENT
lib.flexformContent {
    table = tt_content
    select {
        pidInList = this
    }

    renderObj = COA
    renderObj {
        10 = TEXT
        10 {
            data = flexform: pi_flexform:settings.categories
        }
    }
}

my_content = FLUIDTEMPLATE
my_content {
  variables {
    categories = TEXT
    categories.data = flexform: pi_flexform:categories
  }
}

my_content = FLUIDTEMPLATE
my_content {
  dataProcessing {
    10 = TYPO3\CMS\Frontend\DataProcessing\FlexFormProcessor
    10.fieldName = my_flexform_field
    10.as = myOutputVariable
  }
}

Steps to Perform (Editor)

After inserting a plugin, the editor can configure this plugin by switching to the tab "Plugin" or whatever string you defined to replace this.

Credits

Some of the examples were taken from the extensions georgringer/news (by Georg Ringer) and bk2k/bootstrap-package (by Benjamin Kott).

Further enhancements by the TYPO3 community are welcome!

T3DataStructure

More information on the used data structures within FlexForms can be found in these following chapters: