This covers the documentation on how to create content elements in Contao 4.6
and up. In previous Contao version, Content elements must extend from \Contao\ContentElement
and then be registered via the $GLOBAL['TL_CTE']
array.
In Contao, Content Elements are the fundamental content blocks. In its simplest form it is a fragment controller which receives data in form of a content model and returns a response.
These elements are implemented as so called fragment controllers which Contao then renders into the main content, using their defined renderer. See the caching documentation for more information.
Creating a content element is very similar to creating front end modules.
To create a new content element, the following things must be defined and implemented:
Fragment Controller
The actual implementation of the content element is done via a class that extends
from AbstractContentElementController
of the Contao core.
Service Tag
To identify the controller as a Contao content element, the service must be tagged
with service tag contao.content_element
.
Type
The type of a content element is a specific string which is used to identify
the element’s template and DCA palette. The type
can be set in the service
tag. If ommitted the type will be automatically generated by converting the
class name of the controller from pascal case to snake case and removing a possible
Controller
postfix.
Category
All content elements are categorised within the type dropdown of the content element’s
palette. A category
must be defined in the service tag for each content element.
Template
The template name follows the naming convention mentioned beforehand. It prepends
the type of the element with the prefix ce_
.
Usually a content element is based on a specific palette in the tl_content
DCA configuration.
// contao/dca/tl_content.php
$GLOBALS['TL_DCA']['tl_content']['palettes']['my_content_element'] =
'{type_legend},type;{text_legend},text'
;
This very simple palette enables a back end user to fill the (pre-existing) field
text
via the create and edit view of this content element.
The controller for this content element could look like this:
// src/Controller/ContentElement/MyContentElementController.php
namespace App\Controller\ContentElement;
use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\ServiceAnnotation\ContentElement;
use Contao\Template;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
/**
* @ContentElement(category="texts")
*/
class MyContentElementController extends AbstractContentElementController
{
protected function getResponse(Template $template, ContentModel $model, Request $request): ?Response
{
$template->text = $model->text;
return $template->getResponse();
}
}
In this example the service tag was implemented via annotations.
Using the naming convention for templates mentioned above, the final template name
for this content element will be ce_my_content_element
:
<!-- contao/templates/ce_my_content_element.html5 -->
<div class="my-content-element">
<?= $this->text; ?>
</div>
A template instance of this template will automatically be generated and passed to the controller’s main method. The controller returns the parsed template as a response.
The contao.content_element
tag can be configured further more. The following
options are available.
Option | Type | Description |
---|---|---|
name | string |
Must be contao.content_element . |
category | string |
Defines in which option group this content element will be placed in the content element selector. |
template | string |
Optional: Override the generated template name. |
type | string |
Optional: The type mentioned in Type can be customized. |
renderer | string |
Optional: The renderer can be changed to inline or esi . Defaults to forward . See Caching Fragments for more details. |
method | string |
Optional: Which method should be invoked on the controller. |
A more complex example of a Content Element could look like this.
# config/services.yaml
services:
App\Controller\ContentElement\MyContentElementController:
tags:
-
name: contao.content_element
category: texts
template: ce_my_content_element
method: getCustomResponse
renderer: esi
type: my_custom_type
In order to have a nice label in the back end, we also need to add a translation for our content element - otherwise it will only be named my_content_element. The translation needs to be set as follows:
// contao/languages/en/default.php
$GLOBALS['TL_LANG']['CTE']['my_content_element'] = [
'My Content Element',
'A Content Element for testing purposes.',
];
This feature is only available in Contao 4.8 and later.
Instead of tagging the content element controller service via the service configuration,
the service tag can also be configured through annotations, as already used in the
code example above. The annotation can be used on the class of the content element,
if the class is invokable (has an __invoke
method) or extends from the AbstractFragmentController
.
Otherwise the annotation can be used on the method that will deliver the response.
The following example uses the annotation and only defines the category under which the module should be displayed within the type select of the back end, as this is the only required property that needs to be set.
// src/Controller/ContentElement/ExampleController.php
namespace App\Controller\ContentElement;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\ServiceAnnotation\ContentElement;
use Contao\ContentModel;
use Contao\Template;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
/**
* @ContentElement(category="texts")
*/
class ExampleController extends AbstractContentElementController
{
protected function getResponse(Template $template, ContentModel $model, Request $request): ?Response
{
return $template->getResponse();
}
}
Every other property is inferred from the class name or uses the default. The element
type in this case will be example
, the template will be ce_example
and the
renderer will be forward
.
The following example sets the type of the element to my_example
, puts it in the
texts
category, sets the template name to ce_some_example
and defines the renderer
to be forward
(which is the default):
/**
* @ContentElement("my_example",
* category="texts",
* template="ce_some_example",
* renderer="forward"
* )
*/
class ExampleController extends AbstractContentElementController
{
}
You can also use class constants within annotations. This can be helpful to make the module’s type a reusable reference:
/**
* @ContentElement(ExampleController::TYPE, category="miscellaneous")
*/
class ExampleController extends AbstractContentElementController
{
public const TYPE = 'my_element';
}
// contao/dca/tl_module.php
use App\Controller\ContentElement\ExampleController;
$GLOBALS['TL_DCA']['tl_content']['palettes'][ExampleController::TYPE] =
'{type_legend},type;{text_legend},text'
;
// contao/languages/en/default.php
use App\Controller\ContentElement\ExampleController;
$GLOBALS['TL_LANG']['CTE'][ExampleController::TYPE] = [
'My Example Element',
'A Content Element for testing purposes.',
];
This feature is only available in Contao 4.9.10 and later.
If your fragment extends from AbstractContentElementController
(or just AbstractFragmentController
)
you can use $this->getPageModel()
in order to receive the \Contao\PageModel
object of the currently rendered page of Contao’s site structure.
// src/Controller/ContentElement/MyContentElementController.php
namespace App\Controller\ContentElement;
use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\ServiceAnnotation\ContentElement;
use Contao\Template;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
/**
* @ContentElement(category="texts")
*/
class MyContentElementController extends AbstractContentElementController
{
protected function getResponse(Template $template, ContentModel $model, Request $request): ?Response
{
$page = $this->getPageModel();
// Get some information about the current page
$template->rootTitle = $page->rootPageTitle ?: $page->rootTitle;
return $template->getResponse();
}
}