Content Elements

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.

Definition

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 the service tag contao.content_element - and the tag will hold the following additional information:

  • Type
    The type of a content element is a specific string which is used to identify the element’s template (if not defined) and DCA palette. If omitted the type will be automatically inferred 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. The default category is miscellaneous when using PHP attributes to tag the service.

  • Template
    If not specified, the Twig template name follows is the type and prepends it with the content_element/ path, i.e. content_element/<type>.html.twig.

Example

Consider this very simple example of a content element:

// src/Controller/ContentElement/ExampleElementController.php
namespace App\Controller\ContentElement;

use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\DependencyInjection\Attribute\AsContentElement;
use Contao\CoreBundle\Twig\FragmentTemplate;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

#[AsContentElement]
class ExampleElementController extends AbstractContentElementController
{
    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        $template->set('text', $model->text);
        
        return $template->getResponse();
    }
}

In this example the service tag was implemented via PHP attributes (see the different registration types below).

In order to be able to set the options for this content element and fill it with content in the back end, we also need to define a specific palette in the tl_content DCA configuration. The palette key is based on the type of the content element. Since we did not specify a type in our example it defaults to example_element as explained above.

// contao/dca/tl_content.php
$GLOBALS['TL_DCA']['tl_content']['palettes']['example_element'] = '
    {type_legend},type,headline;
    {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. Now we create a basic Twig template for the output:

{# templates/content_element/example_element.html.twig #}
{% extends "@Contao/content_element/_base.html.twig" %}

{% block content %}
    {{ text }}
{% endblock %}

A “fragment template” instance of this template will automatically be generated and passed to the controller’s getResponse() method. The controller then returns the rendered Twig template as a response.

Registration

As mentioned previously a content element is registered by registering a controller as a service and tagging it with the contao.content_element service tag. The service tag supports the following options:

Applying the service tag can either be done via PHP attributes, annotations or via the YAML configuration.

// src/Controller/ContentElement/ExampleElementController.php
namespace App\Controller\ContentElement;

use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\DependencyInjection\Attribute\AsContentElement;
use Contao\CoreBundle\Twig\FragmentTemplate;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

#[AsContentElement(category: 'texts')]
class ExampleElementController extends AbstractContentElementController
{
    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        return $template->getResponse();
    }
}

// src/Controller/ContentElement/ExampleElementController.php
namespace App\Controller\ContentElement;

use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\DependencyInjection\Attribute\AsContentElement;
use Contao\CoreBundle\Twig\FragmentTemplate;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

#[AsContentElement(
    type: 'example_element',
    category: 'texts',
    template: 'content_element/example',
    method: '__invoke', 
    renderer: 'forward',
    nestedFragments: false,
    priority: 100,
)]
class ExampleElementController extends AbstractContentElementController
{
    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        return $template->getResponse();
    }
}

// src/Controller/ContentElement/ExampleElementController.php
namespace App\Controller\ContentElement;

use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\ServiceAnnotation\ContentElement;
use Contao\CoreBundle\Twig\FragmentTemplate;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

/**
 * @ContentElement(category="texts")
 */
class ExampleElementController extends AbstractContentElementController
{
    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        return $template->getResponse();
    }
}

// src/Controller/ContentElement/ExampleElementController.php
namespace App\Controller\ContentElement;

use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\ServiceAnnotation\ContentElement;
use Contao\CoreBundle\Twig\FragmentTemplate;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

/**
 * @ContentElement("example_element", "texts", "ce_example", "__invoke", "forward")
 */
class ExampleElementController extends AbstractContentElementController
{
    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        return $template->getResponse();
    }
}

# config/services.yaml
services:
    App\Controller\ContentElement\ExampleElementController:
        tags:
            -
                name: contao.content_element
                category: texts

// src/Controller/ContentElement/ExampleElementController.php
namespace App\Controller\ContentElement;

use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\Twig\FragmentTemplate;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class ExampleElementController extends AbstractContentElementController
{
    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        return $template->getResponse();
    }
}

# config/services.yaml
services:
    App\Controller\ContentElement\ExampleElementController:
        tags:
            -
                name: contao.content_element
                category: texts
                template: ce_example
                renderer: forward
                method: __invoke

Translations

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 example_element. The translation needs to be set as follows:

# translations/contao_default.en.yaml
CTE:
    example_element:
        - My Content Element
        - A Content Element for testing purposes.

Page Model

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/ExampleElementController.php
namespace App\Controller\ContentElement;

use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\DependencyInjection\Attribute\AsContentElement;
use Contao\CoreBundle\Twig\FragmentTemplate;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

#[AsContentElement(category: 'texts')]
class ExampleElementController extends AbstractContentElementController
{
    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        $page = $this->getPageModel();

        // Get some information about the current page
        $template->set('rootTitle', $page->rootPageTitle ?: $page->rootTitle);
        
        return $template->getResponse();
    }
}

Nested Fragments

An alternative approach to the aforementioned wrapper elements are so called “nested fragments”. These allow you to nest other content elements within a parent content element for which nested fragments are enabled. The following screenshot shows the Element group content element of the Contao Core:

Just as with page articles, news archives, etc. this content element allows you to edit its children via which then works the same way as within the article of a page.

Allowing nested fragments for your content element works via the nestedFragments option in the service tag:

#[AsContentElement(nestedFragments: true)]
class ExampleElementController extends AbstractContentElementController
{
    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        return $template->getResponse();
    }
}

/**
 * @ContentElement(category="miscellaneous", nestedFragments=true)
 */
class ExampleElementController extends AbstractContentElementController
{
    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        return $template->getResponse();
    }
}

services:
    App\Controller\ContentElement\ExampleElementController:
        tags:
            -
                name: contao.content_element
                nestedFragments: true

With nested fragments it is also possible to restrict the fragment’s children to specific content element types. Say you want to implement a specific slider content element which should only allow images and videos as its children. Then instead of defining true for the tag’s nestedFragments option you can instead pass an additional option called allowedTypes:

#[AsContentElement(nestedFragments: ['allowedTypes' => ['image', 'video']])]
class ExampleElementController extends AbstractContentElementController
{
    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        return $template->getResponse();
    }
}

/**
 * @ContentElement(category="miscellaneous", nestedFragments={"allowedTypes" = {"image", "video"}})
 */
class ExampleElementController extends AbstractContentElementController
{
    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        return $template->getResponse();
    }
}

services:
    App\Controller\ContentElement\ExampleElementController:
        tags:
            -
                name: contao.content_element
                nestedFragments:
                    allowedTypes: ['image', 'video']

Now all you have to do is render these fragments in your template. The AbstractContentElementController from which your content element likely extends from automatically passes the available nested fragments to your template within the nested_fragments template variable. This will be a collection of ContentElementReference objects which you can render via the content_element() Twig function:

{# templates/content_element/example.html.twig #}
{% extends "@Contao/content_element/_base.html.twig" %}

{% block content %}
    {% for fragment in nested_fragments %}
        {{ content_element(fragment) }}
    {% endfor %}
{% endblock %}

Wrapper Elements

Before the introduction of nested fragments in Contao, there were special content elements called “wrappers” which you insert before and after one or a group of content elements. These wrappers affect the back end view, indicating that all elements contained within the two wrappers are descendants of the parent wrapper. The wrapper content elements typically consist of a startand stop element, though there are also wrappers of type single and separator. The start element typically opens a specific HTML tag, while the stop element will close it again.

In order to define that a content element is a wrapper of a specific type, it needs to be registered in the $GLOBALS['TL_WRAPPERS'] array in your contao/config/config.php. The $GLOBALS['TL_WRAPPERS'] array holds the element types for each type of wrapper. For example:

// contao/config.php
$GLOBALS['TL_WRAPPERS']['start'][] = 'my_start_element';
$GLOBALS['TL_WRAPPERS']['stop'][] = 'my_stop_element';

// src/Controller/ContentElement/MyWrapperElementController.php
namespace App\Controller\ContentElement;

use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\DependencyInjection\Attribute\AsContentElement;
use Contao\CoreBundle\Twig\FragmentTemplate;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

#[AsContentElement('my_start_element')]
#[AsContentElement('my_stop_element')]
class MyWrapperElementController extends AbstractContentElementController
{
    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        if ($this->isBackendScope($request)) {
            return new Response();
        }

        return $template->getResponse();
    }
}

Read More

• Manipulate and create palettes
• Create and use templates
• Customize Caching