spooner-web / tcabuilder
Utility to easily maintain and create your TCA forms
Fund package maintenance!
Other
Requires
- php: >= 7.4, < 8.4
- typo3/cms-backend: ^v11.5 || ^v12.4 || ^v13.2
- typo3/cms-core: ^v11.5 || ^v12.4 || ^v13.2
Requires (Dev)
- phpunit/phpunit: ^9.5
- ssch/typo3-rector: ^2.4
This package is auto-updated.
Last update: 2024-11-03 08:07:41 UTC
README
What does it do?
With the TCA builder you have the possibility to create or change the fields in type list in an easy and speaking way.
Times of semicolons within field names are gone.
For example:
- Compose the field list for the form of a content element or any other record
- Change the types of existing definitions
Introducing TcaCreator in v1.6.0
With the TCA creator you have the possibility to create TCA forms
from scratch and do not need to think about the configuration of the default fields
like the ctrl
section or the default fields in the columns
section.
More to see in the Examples Section
Installation
Installation via composer
composer require spooner-web/tcabuilder
:warning: In a composer install, the package won't be in typo3conf/ext folder but in vendor
Installation via classic mode
- Head to https://extensions.typo3.org/extension/tcabuilder
- Download the ZIP file
- Upload it to your TYPO3 instance using non-composer mode
Installation via Extension Manager
- Update your extension list
- Search for "tcabuilder"
- Install
Composer fails checking out this package
As composer is not able to detect the ZIP archive of a self-hosted GitLab instance, there may occur problems when deploying or building a project with this package.
To fix this issue, you need to add the GitLab built-in packagist API into the repositories
section
of your project composer.json:
{
"type": "composer",
"url": "https://git.spooner.io/api/v4/group/8/-/packages/composer/"
}
Usage
General usage
Recommendation is to use the TcaBuilder
in the php files of your Configuration/TCA/Overrides/
folder of your extension.
- Instantiate the
TcaBuilder
class - Set the table and type to configure (may also be a not existing type yet)
- Use the methods to manipulate
- Save to the TCA
- Flush caches
- See result
Methods
Main methods
Method name | Description | Parameters |
---|---|---|
setTable | Sets the table to load configuration from | string $tableName |
setType | Sets the type to load configuration from | string $typeName |
load | Loads configuration if it's an existing type | |
loadConfiguration | Shorter method to run setTable , setType and load at once | string $tableName string $typeName |
useLocalLangFile | Set a locallang file (beginning with EXT: ) to use in labels | string $localLangFile |
saveToTca | Saves the manipulated configuration to TCA | bool $resetAfterSave (optional) |
returnAsArray | Instead of saving the configuration it returns it directly as array |
Manipulating types
Method name | Description | Parameters |
---|---|---|
addField | Adds a field to selected type | string $typeName string $position (optional) string $alternativeLabel (optional) |
removeField | Removes a field from selected type | string $fieldName |
moveField | Moves a field to a new position (alternatively with a new label) | string $fieldName string $newPositionstring $newLabel (optional) |
addPalette | Adds an existing palette to selected type | string $paletteName string $position (optional)string $alternativeLabel (optional) |
removePalette | Removes a palette from selected type | string $paletteName |
movePalette | Moves a palette to a new position (alternatively with a new label) | string $paletteName string $newPosition string $newLabel (optional) |
addDiv | Adds a div (tab) to selected type | string $divName string $label |
removeDiv | Removes a div (tab) from selected type, either by position (index, beginning with 0) or by label | string |int $positionOrLabel |
addOverride | Adds a custom override of a field | string $fieldName array $configuration |
initialize | Initializes the type with an empty list |
Manipulating palettes
Method name | Description | Parameters |
---|---|---|
addCustomPalette | Creates a new palette (and optionally inserts it directly to given position) | string $paletteId array $fields string $label (optional) string $position (optional) |
addFieldToPalette | Adds a field to a palette | string $paletteId string $field string $position (optional) |
removeFieldFromPalette | Removes a field from a palette | string $paletteId string $field |
initializePalette | Initializes the palette with an empty list | string $paletteId |
Helper methods
Method name | Description | Parameters | Returns |
---|---|---|---|
getPaletteString | Finds the complete palette string which is used in list (for using it in position strings) | string $paletteName | string The complete palette string with --palette-- and the possible label config |
getDivString | Finds the complete div string which is used in list (for using it in position strings), either by position (index, beginning with 0) or by label | string |int $positionOrLabel | string The complete palette string with --div-- and the div's label |
Possible values for positioning fields, palettes or divs
Value | Description |
---|---|
before:<item> | Moves the item before the given item |
after:<item> | Moves the item after the given item |
replace:<item> | Replaces the given item |
Examples (TCA builder)
Add an own content element
$tcaBuilder = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\SpoonerWeb\TcaBuilder\TcaBuilder::class);
$tcaBuilder
->setTable('tt_content') // define table
->setType('test') // define type
->addDiv('General')
->addField('header', '', 'Top header!!')
->addField('bodytext')
->addField('subheader', 'after:header')
->addField('layout', 'before:header')
->addDiv('Extra')
->addPalette('access')
->addPalette('hidden', 'after:bodytext', 'Alternative label')
->saveToTca(); // save to TCA
Change existing configurations
$tcaBuilder = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\SpoonerWeb\TcaBuilder\TcaBuilder::class);
$tcaBuilder
->setTable('pages') // define table
->setType(\TYPO3\CMS\Frontend\Page\PageRepository::DOKTYPE_LINK) // define type
->load() // load definitions
->removeField('doktype')
->removePalette('external')
->removeDiv(1)
->addPalette('external', 'after:--palette--;;layout')
->saveToTca(); // save back to TCA
$tcaBuilder = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\SpoonerWeb\TcaBuilder\TcaBuilder::class);
$tcaBuilder
->loadConfiguration('pages', \TYPO3\CMS\Frontend\Page\PageRepository::DOKTYPE_MOUNTPOINT)
->removeDiv('LLL:EXT:frontend/Resources/Private/Language/locallang_tca.xlf:pages.tabs.metadata')
->movePalette('title', 'after:' . $tcaBuilder->getPaletteString('abstract'), 'New title')
->addOverride(
'title',
[
'label' => 'New title',
'config' => [
'renderType' => 'inputLink'
]
]
)
->saveToTca();
Use language file
$tcaBuilder = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\SpoonerWeb\TcaBuilder\TcaBuilder::class);
$tcaBuilder
->loadConfiguration('pages', \TYPO3\CMS\Frontend\Page\PageRepository::DOKTYPE_MOUNTPOINT)
->useLocalLangFile('EXT:my_extension/Resources/Private/Language/locallang.xlf')
->addField('new_field', '', 'LANG:new_field') // Used label: "LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:new_field"
->saveToTca();
Do minimal changes
$tcaBuilder = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\SpoonerWeb\TcaBuilder\TcaBuilder::class);
$tcaBuilder
->loadConfiguration('tt_content', 'textmedia')
->removePalette('headers')
->saveToTca();
Examples (Tca Creator)
Creating TCA configuration for a new table (inside custom extension)
// Returns the default values of ctrl section
// By default language, version and sorting options are set
// These options can be unset and additional overridden fields can be set
$configuration['ctrl'] = \SpoonerWeb\TcaBuilder\TcaCreator::getControlConfiguration(
'title',
'label'
);
// Returns the default columns depending on the ctrl section configuration
// Example: If ctrl section includes language, this method returns the field configuration
// for all language fields (sys_language_uid, l10n_parent, l10n_diffsource, l10n_source)
$configuration['columns'] = \SpoonerWeb\TcaBuilder\TcaCreator::getColumnsConfiguration(
$configuration['ctrl'],
'tx_extension_domain_model_record',
[
'title' => [
'label' => 'My label',
'config' => [
'type' => 'input'
]
]
]
);
// Uses TcaBuilder class to create the configuration for the TCA form
$configuration['types'][] = \SpoonerWeb\TcaBuilder\TcaCreator::buildTypesConfiguration()
->addDiv('General')
->addField('title')
->addField('subtitle')
->addDiv('Categories')
->addField('categories')
->returnAsArray();
// Now return TCA configuration
return $configuration;