b13 / container
Create Custom Container Content Elements for TYPO3
Installs: 1 650 699
Dependents: 39
Suggesters: 7
Security: 0
Stars: 167
Watchers: 23
Forks: 62
Open Issues: 46
Type:typo3-cms-extension
Requires
- doctrine/dbal: ~2.13.1 || ~3.4
- typo3/cms-backend: ^11.5 || ^12.4 || ^10.4
Requires (Dev)
- b13/container-example: dev-master
- codeception/codeception: ^5.0 || ^4.1
- codeception/module-asserts: ^3.0 || ^1.0
- codeception/module-db: ^3.0 || ^1.0
- codeception/module-webdriver: ^3.1 || ^1.0
- friendsofphp/php-cs-fixer: ~3.9.0
- ichhabrecht/content-defender: ^3.2
- phpstan/phpstan: ^1.4.8
- typo3/cms-fluid-styled-content: ^11.5 || ^12.4
- typo3/cms-info: ^11.5 || ^12.4
- typo3/cms-install: ^11.5 || ^12.4
- typo3/cms-workspaces: ^11.5 || ^12.4
- typo3/coding-standards: ^0.5.0
- typo3/testing-framework: ^7
Replaces
- typo3-ter/container: 2.3.6
- dev-master
- 2.3.6
- 2.3.5
- 2.3.3
- 2.3.2
- 2.3.1
- 2.3.0
- 2.2.5
- 2.2.4
- 2.2.3
- 2.2.2
- 2.2.1
- 2.2.0
- 2.1.2
- 2.1.1
- 2.1.0
- 2.0.5
- 2.0.4
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0.0
- 1.6.1
- 1.6.0
- 1.5.0
- 1.4.2
- 1.4.1
- 1.4.0
- 1.3.1
- 1.3.0
- 1.2.0
- 1.1.1
- 1.1.0
- 1.0.0
- dev-task/dev-main
- dev-bugfix/535
- dev-feature/events-4
- dev-e4
- dev-issue-499
- dev-feature/new-content-element-link-2
- dev-test-config
- dev-feature/new-content-element-link-3
- dev-feature/new-content-element-link
- dev-feature/events-3
- dev-feature/events-2
- dev-task/new-ce-label
- dev-task/tests-13.2
- dev-feature/events
- dev-test-493
- dev-task/phpunit-version
- dev-task/colpos-parent
- dev-v13-testing-2
- dev-task/v13-work
- dev-kp
- dev-task/error-handling
- dev-393-fix-ci
- dev-apple-patch-1-testing
- dev-test-12
- dev-task/v12-ll
- dev-v12-test
- dev-390-2
- dev-task/issue-342
- dev-master8
- dev-master7
This package is auto-updated.
Last update: 2024-10-08 06:33:59 UTC
README
EXT:container - A TYPO3 Extension for creating nested content elements
Features
- Simple amazing containers (grids) as custom TYPO3 Content Elements
- No default containers, everything will be built the way its needed for a project
- Supports multilanguage (connected or free mode (mixed mode not supported))
- Supports workspaces
- Supports colPos-restrictions if EXT:content_defender >= 3.1.0 is installed
- Frontend Rendering via DataProcessor and Fluid templates
Why did we create another "Grid" extension?
At b13 we've been long supporters and fans of gridelements, which we are thankful for and we used it in the past with great pleasure.
However, we had our pain points in the past with all solutions we've evaluted and worked with. These are our reasons:
- We wanted an extension that works with multiple versions of TYPO3 Core with the same extension, to support our company's TYPO3 upgrade strategy.
- We wanted to overcome issues when dealing with
colPos
field and dislike any fixed value which isn't fully compatible with TYPO3 Core. - We wanted an extension that is fully tested with multilingual and workspaces functionality.
- We wanted an extension that only does one thing: EXT:container ONLY adds tools to create and render container elements, and nothing else. No FlexForms, no permission handling or custom rendering.
- We wanted an extension where every grid has its own Content Type (CType) making it as close to TYPO3 Core functionality as possible.
- We wanted an extension where the configuration of a grid container element is located at one single place to make creation of custom containers easy.
- We wanted an extension that has a progressive development workflow: We were working with new projects in TYPO3 v10 sprint releases and needed custom container elements and did not want to wait until TYPO3 v10 LTS.
Installation
Install this extension via composer req b13/container
or download it from the TYPO3 Extension Repository and activate
the extension in the Extension Manager of your TYPO3 installation.
Once installed, add a custom content element to your sitepackage or theme extension (see "Adding your own container element").
Adding your own container element
- Register your custom container in your sitepackage or theme extension in
Configuration/TCA/Overrides/tt_content.php
as new Content Type - Add TypoScript and your Fluid Template for frontend rendering
- Add an icon in Resources/Public/Icons/
<CType>
.svg
See EXT:container_example for a simple example of a custom container.
Registration of Container Elements
This is an example to create a 2 column container. The code snippet goes into a file in your sitepackage or theme extension in the folder Configuration/TCA/Overrides/
. The file can have any name but it is good practice to name it according to the database table it relates to. In this case this would be 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') );
Methods of the ContainerConfiguration Object
Notes:
- If EXT:content_defender >= 3.1.0 is installed you can use
allowed
,disallowed
andmaxitems
in the column configuration - The container registry does multiple things:
- Adds CType to TCA select items
- Registers your icon
- Adds PageTSconfig for
newContentElement.wizardItems
- Sets
showitem
for this CType (sys_language_uid,CType,tx_container_parent,colPos,hidden
) - Saves the configuration in TCA in
$GLOBALS['TCA']['tt_content']['containerConfiguration'][<CType>]
for further usage
- We provide some default icons you can use, see
Resources/Public/Icons
- container-1col
- container-2col
- container-2col-left
- container-2col-right
- container-3col
- container-4col
TypoScript
The TypoScript is necessary to define the rendering of the container in the frontend. Normally you will place it in your sitepackage or theme extension near the place where you define other stuff regarding your content elements.
templateRootPaths
must be adapted to reflect the path of the html files in your sitepackage or theme extension.
// 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
}
}
}
Options for DataProcessing
Template
The html template file goes in the folder that you have defined in your TypoScript above (see templateRootPaths
). It's important to name it exacly as defined in templateName
in TypoScript, in this case 2ColsWithHeader.html
. The file name is case-sensitive!
<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>
With explicit colPos defined use {children_200|201}
as set in the example above
PSR-14 Events
BeforeContainerConfigurationIsAppliedEvent
- change container configuration for 3rd party extensions container you have installed
- apply same configuration to all or a set of containers (e.g.
gridTemplate
) - Note CType and Grid Structure cannot be changed (but Column Properties of the Grid)
BeforeContainerPreviewIsRendered
change view object, e.g. add variables to view or change paths
Concepts
- Complete registration is done with one PHP call to TCA Registry
- A container in the TYPO3 backend Page module is rendered like a page itself (see View/ContainerLayoutView)
- For backend clipboard and drag & drop
<tx_container_parent>_<colPos>
used in the data-colpos attribute in the wrapping CE-div Element (instead of just the colPos as in the PageLayoutView) - The
<tx_container_parent>_<colPos>
parameter is resolved totx_container_parent
andcolPos
value in DataHandler hooks - When translating a container, all child elements get also translated (the child elements are not explicit listed during the translation dialog)
- Copying or moving children of a container copies or moves translations as well
- Custom definitions make use of custom
colPos
values so site owners build their own elements, no fixedcolPos
given, so no interference with existing solutions - Each container type is just a definition for its own
CType
CLI commands
There's several CLI commands to check/fix the integrity of the containers and their children.
# 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
TODOs
- Integrity proofs
- List module actions
Extension Tests and Coding Guidelines
You can run our test suite for this extension yourself:
- run
composer install
- run
Build/Scripts/runTests.sh -s unit
- run
Build/Scripts/runTests.sh -s functional
- run
Build/Scripts/runTests.sh -s acceptance
See Tests/README.md how to run the tests local (like github-actions runs the tests).
To assure coding guidelines are fullfilled:
- run
.Build/bin/phpstan analyse -c Build/phpstan10.neon
- run
.Build/bin/php-cs-fixer fix --config=Build/php-cs-fixer.php --dry-run --stop-on-violation --using-cache=no
Credits
This extension was created by Achim Fritz in 2020 for b13 GmbH, Stuttgart.
Find examples, use cases and best practices for this extension in our container blog series on b13.com.
Find more TYPO3 extensions we have developed that help us deliver value in client projects. As part of the way we work, we focus on testing and best practices to ensure long-term performance, reliability, and results in all our code.