SectionTypes

SectionTypes are the building blocks of a page's content. Many section types can be stacked on a single page to create a complete web page. Each section type is responsible for rendering its own content.

All SectionType controllers are stored in their own directory structure under ./src/Controller/SectionTypes/.

Cross-Project SectionTypes

SectionTypes are not generally project-specific, and can be shared across multiple projects. This allows you to create a library of reusable section types that can be dropped into any project.

Built-in SectionTypes

Several sectiion types are built-in and do not exist as options in the site administration panel. These include: - Error404Section: A section that is used to render a 404 error page. - HeaderSection: A section that is used to render the header of a page. - FooterSection: A section that is used to render the footer of a page.

These built-in section types are located in ./src/Controller/SectionTypesBuiltin/

Creating a New SectionType

You can create a new SectionType by issuing the following command:

ddev symfony console make:section:type

This command will prompt you for information about your new section type and then create a new collection of files in the ./src/Controller/SectionTypes/ directory. The files included with each new section type are:

.php: The PHP controller file for the section type, which is used to handle the incoming request and render the section's content by passing values to the Twig template.
.twig: The Twig template file for the section type, which is used to render the section's content.
.scss: The stylesheet file for the section type. If you are using Tailwind (which we recommend and include by default), this file will likely remain empty while Tailwind classes are applied in the Twig template instead. CSS and SASS syntax are both supported here.

Section types will appear in the administration panel as choices when using a page's section editor interface (shown as buttons to the right below):

Section Types

Explore Section Types In the Admin Panel

If you haven't already, now is a good time to explore the section types in the admin panel. First ensure you have the admin panel pulled up:

ddev admin

Then navigate to any page and click on edit. Go to the section editor tab and play around with adding, editing, sorting, and deleting sections.

Reviewing SectionType Files

Here are the files included with all newly generated section types:

PHP ControllerTwig TemplateSCSS Stylesheet

The PHP controller has two main methods:

buildForm(): This method is used to build the form for the section type that allows it to be customized in the administration panel.
handlePageSectionRequest(): This method is called when the section type is rendered on a page. It takes in the request, the page, the section, and the page parameters, and returns a response that renders the section's content using the Twig template.

Php

<?php  /* Generated with make:section:type */

// ...

#[SectionTypeDefinition(
    uuid: '2173ac8d-5368-4f80-80b2-64154fb137f7',
    iconHTML: '<i class="fa-solid fa-cube"></i>',
    name: 'My Awesome Block',
    description: 'For demonstration purposes only',
    enabled: true
)]
class MyAwesomeSection extends AbstractSection
{
    public function __construct(

    ) {}

    final public function buildForm(FormBuilderInterface $formBuilder, array $jsonData): FormBuilderInterface
    {
        return parent::buildForm($formBuilder, $jsonData);
    }

    final public function handlePageSectionRequest(
        Request        $request,
        Page           $page,
        Section        $section,
        PageParameters $pageParameters,
    ): Response {
        return $this->render(
            "@SectionTypes/MyAwesomeBlock/my_awesome_block_section.html.twig",
            [
                "request" => $request,
                "page" => $page,
                "section" => $section,
                "pageParameters" => $pageParameters,
            ]
        );
    }
}

By default, the Twig template will simply dump the section and section JSON data to ease development. You can use two blocks for rendering a section's content:

{% block section %}: The default content block, nested inside of a page level wrapper for easy containment on large screen sizes.
{% block sectionOuter %}: Escapes the page's default wrapper around a section for when you need to exceed the bleeding edge of the page.

Twig

{# Generated with make:section:type #}
{% extends 'section_base.html.twig' %}

{# OPTIONS *********************************************************************
***************************************************************************** #}

{% set options={

}|merge(options|default({})) %}

{# TEMPLATE ********************************************************************
***************************************************************************** #}

{% block section %}

    {# by default, we dump the section's content to ease development #}
    {{ dump(section) }}
    {{ dump(section.json) }}

{% endblock %}

The stylesheet rules provided by default are scoped specifically to the section type. These stylesheets get added to the asset bundler and are compiled at build time. If you are using Tailwind, this file will likely remain empty while Tailwind classes are applied in the Twig template instead.

Scss

/* Generated with make:section:type */

section[data-section-handler="MyAwesomeBlock"] { // full width of page
  .section-content { // inner container for all section elements

  }
}

In review, the PHP SectionType controller receives important information and then returns the output of the Twig template.

Making the SectionType Configurable

SectionType Form

The buildForm() Method

SectionType controllers implement a buildForm() method that leverages Symfony Forms to allow users to configure their section after adding it to a page. This method receives a FormBuilderInterface with a few form fields already added:

Php

<?php

public function buildForm(FormBuilderInterface $formBuilder, array $jsonData): FormBuilderInterface
{
    /**
      * $formBuilder is pre-populated with the following fields:
      * - save:    button
      * - cancel:  button
      * - delete:  button
      * - title:   text input
      * - tagline: text input
      * - content: html editor
      */
    return parent::buildForm($formBuilder, $jsonData);
}

Removing Fields

If you do not need a field, you can remove it from the form builder. For example, if you do not need the tagline field, you can remove it like this:

Php

<?php

public function buildForm(FormBuilderInterface $formBuilder, array $jsonData): FormBuilderInterface
{
    // remove the tagline field
    $formBuilder->remove('tagline');
    return parent::buildForm($formBuilder, $jsonData);
}

Adding Fields

You can add additional fields to the form builder using the add() method. As mentioned earlier, fields will use the Symfony Forms syntax. For example, if you want to add a externalLink field, you can do so like this:

Php

<?php

public function buildForm(FormBuilderInterface $formBuilder, array $jsonData): FormBuilderInterface
{
    // add an external link field
    $formBuilder->add('externalLink', TextType::class, [
        'label' => 'External Link',
        'required' => false,
    ]);
    return parent::buildForm($formBuilder, $jsonData);
}

Reading Form Data In The Controller

All form data is transformed into JSON and stored in the database. You can access this data in your handlePageSectionRequest() method by using the $section->json property. This property contains the JSON data that was submitted when the form was saved. You can access the data and pass it to twig like this:

Php

<?php

public function handlePageSectionRequest(
    Request        $request,
    Page           $page,
    Section        $section,
    PageParameters $pageParameters,
): Response {
    // access the JSON data
    $jsonData = $section->getJson() ?: [];

    // get the external link field value
    $externalLink = $jsonData['externalLink'] ?? null;

    return $this->render(
        "@SectionTypes/MyAwesomeBlock/my_awesome_block_section.html.twig",
        [
            "request" => $request,
            "page" => $page,
            "section" => $section,
            "pageParameters" => $pageParameters,
            "externalLink" => $externalLink,
        ]
    );
}

Accessing Related Entities

Relational entities (such as an associated gallery image) will only be stored with an _id key in the JSON data. This is done to prevent circular references and to keep the JSON data lightweight.

If you need to access the full entity, you will need to use this id to query the database for them.

Saving Changes to a SectionType

Whenever you modify a SectionType's SectionTypeDefinition attribute, you will need to synchronize changes to the database. This is done by running the following command:

ddev symfony console app:sync

Deleting a SectionType

Because SectionType controllers are registered to the database, they are given a UUID for mapping purposes. To delete a SectionType controller, you will need to grab the UUID of the controller you want to delete from the SectionTypeDefinition portion of the code.

ddev symfony console unmake:section:type

This command will prompt you for the UUID of the SectionType controller you want to delete. Once you provide the UUID, the command will remove the controller and associated files from the code base and also remove the associated SectionType from the database.

Explore Existing Section Types

At this point, it is a good time to explore the existing section types in the code to see how they are built and configured. You can find them in ./src/Controller/SectionTypes/. Take a look at the buildForm() methods in each section type controller.

Next Up: PageParameters Service