class Section

Same name and namespace in other branches
  1. 9 core/modules/layout_builder/src/Section.php \Drupal\layout_builder\Section
  2. 8.9.x core/modules/layout_builder/src/Section.php \Drupal\layout_builder\Section
  3. 11.x core/modules/layout_builder/src/Section.php \Drupal\layout_builder\Section

Provides a domain object for layout sections.

A section consists of three parts:

  • The layout plugin ID for the layout applied to the section (for example, 'layout_onecol').
  • An array of settings for the layout plugin.
  • An array of components that can be rendered in the section.

Hierarchy

Expanded class hierarchy of Section

See also

\Drupal\Core\Layout\LayoutDefinition

\Drupal\layout_builder\SectionComponent

28 files declare their use of Section
AddSectionController.php in core/modules/layout_builder/src/Controller/AddSectionController.php
ConfigureSectionForm.php in core/modules/layout_builder/src/Form/ConfigureSectionForm.php
DefaultsSectionStorageTest.php in core/modules/layout_builder/tests/src/Kernel/DefaultsSectionStorageTest.php
EntityViewDisplayValidationTest.php in core/tests/Drupal/KernelTests/Core/Entity/EntityViewDisplayValidationTest.php
LayoutBuilderEntityViewDisplay.php in core/modules/layout_builder/src/Entity/LayoutBuilderEntityViewDisplay.php

... See full list

32 string references to 'Section'
AnnotatedClassDiscoveryTest::provideBadAnnotations in core/tests/Drupal/Tests/Component/Plugin/Discovery/AnnotatedClassDiscoveryTest.php
All the Drupal documentation standards tags.
Attachment::buildOptionsForm in core/modules/views/src/Plugin/views/display/Attachment.php
Provide the default form for setting options.
Attachment::submitOptionsForm in core/modules/views/src/Plugin/views/display/Attachment.php
Perform any necessary changes to the form values prior to storage.
Block::buildOptionsForm in core/modules/views/src/Plugin/views/display/Block.php
Provide the default form for setting options.
Block::submitOptionsForm in core/modules/views/src/Plugin/views/display/Block.php
Perform any necessary changes to the form values prior to storage.

... See full list

File

core/modules/layout_builder/src/Section.php, line 21

Namespace

Drupal\layout_builder
View source
class Section implements ThirdPartySettingsInterface {
  
  /**
   * The layout plugin ID.
   *
   * @var string
   */
  protected $layoutId;
  
  /**
   * The layout plugin settings.
   *
   * @var array
   */
  protected $layoutSettings = [];
  
  /**
   * An array of components, keyed by UUID.
   *
   * @var \Drupal\layout_builder\SectionComponent[]
   */
  protected $components = [];
  
  /**
   * Third party settings.
   *
   * An array of key/value pairs keyed by provider.
   *
   * @var array[]
   */
  protected $thirdPartySettings = [];
  
  /**
   * Constructs a new Section.
   *
   * @param string $layout_id
   *   The layout plugin ID.
   * @param array $layout_settings
   *   (optional) The layout plugin settings.
   * @param \Drupal\layout_builder\SectionComponent[] $components
   *   (optional) The components.
   * @param array[] $third_party_settings
   *   (optional) Any third party settings.
   */
  public function __construct($layout_id, array $layout_settings = [], array $components = [], array $third_party_settings = []) {
    $this->layoutId = $layout_id;
    $this->layoutSettings = $layout_settings;
    foreach ($components as $component) {
      $this->setComponent($component);
    }
    $this->thirdPartySettings = $third_party_settings;
  }
  
  /**
   * Returns the renderable array for this section.
   *
   * @param \Drupal\Core\Plugin\Context\ContextInterface[] $contexts
   *   An array of available contexts.
   * @param bool $in_preview
   *   TRUE if the section is being previewed, FALSE otherwise.
   *
   * @return array
   *   A renderable array representing the content of the section.
   */
  public function toRenderArray(array $contexts = [], $in_preview = FALSE) {
    $regions = [];
    foreach ($this->getComponents() as $component) {
      if ($output = $component->toRenderArray($contexts, $in_preview)) {
        $regions[$component->getRegion()][$component->getUuid()] = $output;
      }
    }
    $layout = $this->getLayout($contexts);
    if ($layout instanceof PreviewAwarePluginInterface) {
      $layout->setInPreview($in_preview);
    }
    $build = $layout->build($regions);
    // If an entity was used to build the layout, store it on the build.
    if (!Element::isEmpty($build) && isset($contexts['layout_builder.entity'])) {
      $build['#entity'] = $contexts['layout_builder.entity']->getContextValue();
    }
    return $build;
  }
  
  /**
   * Gets the layout plugin for this section.
   *
   * @param \Drupal\Core\Plugin\Context\ContextInterface[] $contexts
   *   An array of available contexts.
   *
   * @return \Drupal\Core\Layout\LayoutInterface
   *   The layout plugin.
   */
  public function getLayout(array $contexts = []) {
    $layout = $this->layoutPluginManager()
      ->createInstance($this->getLayoutId(), $this->layoutSettings);
    if ($contexts) {
      $this->contextHandler()
        ->applyContextMapping($layout, $contexts);
    }
    return $layout;
  }
  
  /**
   * Gets the layout plugin ID for this section.
   *
   * @return string
   *   The layout plugin ID.
   *
   * @internal
   *   This method should only be used by code responsible for storing the data.
   */
  public function getLayoutId() {
    return $this->layoutId;
  }
  
  /**
   * Gets the layout plugin settings for this section.
   *
   * @return mixed[]
   *   The layout plugin settings.
   *
   * @internal
   *   This method should only be used by code responsible for storing the data.
   */
  public function getLayoutSettings() {
    return $this->getLayout()
      ->getConfiguration();
  }
  
  /**
   * Sets the layout plugin settings for this section.
   *
   * @param mixed[] $layout_settings
   *   The layout plugin settings.
   *
   * @return $this
   */
  public function setLayoutSettings(array $layout_settings) {
    $this->layoutSettings = $layout_settings;
    return $this;
  }
  
  /**
   * Gets the default region.
   *
   * @return string
   *   The machine-readable name of the default region.
   */
  public function getDefaultRegion() {
    return $this->layoutPluginManager()
      ->getDefinition($this->getLayoutId())
      ->getDefaultRegion();
  }
  
  /**
   * Returns the components of the section.
   *
   * @return \Drupal\layout_builder\SectionComponent[]
   *   An array of components, keyed by the component UUID.
   */
  public function getComponents() {
    return $this->components;
  }
  
  /**
   * Gets the component for a given UUID.
   *
   * @param string $uuid
   *   The UUID of the component to retrieve.
   *
   * @return \Drupal\layout_builder\SectionComponent
   *   The component.
   *
   * @throws \InvalidArgumentException
   *   Thrown when the expected UUID does not exist.
   */
  public function getComponent($uuid) {
    if (!isset($this->components[$uuid])) {
      throw new \InvalidArgumentException(sprintf('Invalid UUID "%s"', $uuid));
    }
    return $this->components[$uuid];
  }
  
  /**
   * Helper method to set a component.
   *
   * @param \Drupal\layout_builder\SectionComponent $component
   *   The component.
   *
   * @return $this
   */
  protected function setComponent(SectionComponent $component) {
    $this->components[$component->getUuid()] = $component;
    return $this;
  }
  
  /**
   * Removes a given component from a region.
   *
   * @param string $uuid
   *   The UUID of the component to remove.
   *
   * @return $this
   */
  public function removeComponent($uuid) {
    unset($this->components[$uuid]);
    return $this;
  }
  
  /**
   * Appends a component to the end of a region.
   *
   * @param \Drupal\layout_builder\SectionComponent $component
   *   The component being appended.
   *
   * @return $this
   */
  public function appendComponent(SectionComponent $component) {
    $component->setWeight($this->getNextHighestWeight($component->getRegion()));
    $this->setComponent($component);
    return $this;
  }
  
  /**
   * Returns the next highest weight of the component in a region.
   *
   * @param string $region
   *   The region name.
   *
   * @return int
   *   A number higher than the highest weight of the component in the region.
   */
  protected function getNextHighestWeight($region) {
    $components = $this->getComponentsByRegion($region);
    $weights = array_map(function (SectionComponent $component) {
      return $component->getWeight();
    }, $components);
    return $weights ? max($weights) + 1 : 0;
  }
  
  /**
   * Gets the components for a specific region.
   *
   * @param string $region
   *   The region name.
   *
   * @return \Drupal\layout_builder\SectionComponent[]
   *   An array of components in the specified region, sorted by weight.
   */
  public function getComponentsByRegion($region) {
    $components = array_filter($this->getComponents(), function (SectionComponent $component) use ($region) {
      return $component->getRegion() === $region;
    });
    uasort($components, function (SectionComponent $a, SectionComponent $b) {
      return $a->getWeight() <=> $b->getWeight();
    });
    return $components;
  }
  
  /**
   * Inserts a component after a specified existing component.
   *
   * @param string $preceding_uuid
   *   The UUID of the existing component to insert after.
   * @param \Drupal\layout_builder\SectionComponent $component
   *   The component being inserted.
   *
   * @return $this
   *
   * @throws \InvalidArgumentException
   *   Thrown when the expected UUID does not exist.
   */
  public function insertAfterComponent($preceding_uuid, SectionComponent $component) {
    // Find the delta of the specified UUID.
    $uuids = array_keys($this->getComponentsByRegion($component->getRegion()));
    $delta = array_search($preceding_uuid, $uuids, TRUE);
    if ($delta === FALSE) {
      throw new \InvalidArgumentException(sprintf('Invalid preceding UUID "%s"', $preceding_uuid));
    }
    return $this->insertComponent($delta + 1, $component);
  }
  
  /**
   * Inserts a component at a specified delta.
   *
   * @param int $delta
   *   The zero-based delta in which to insert the component.
   * @param \Drupal\layout_builder\SectionComponent $new_component
   *   The component being inserted.
   *
   * @return $this
   *
   * @throws \OutOfBoundsException
   *   Thrown when the specified delta is invalid.
   */
  public function insertComponent($delta, SectionComponent $new_component) {
    $components = $this->getComponentsByRegion($new_component->getRegion());
    $count = count($components);
    if ($delta > $count) {
      throw new \OutOfBoundsException(sprintf('Invalid delta "%s" for the "%s" component', $delta, $new_component->getUuid()));
    }
    // If the delta is the end of the list, append the component instead.
    if ($delta === $count) {
      return $this->appendComponent($new_component);
    }
    // Find the weight of the component that exists at the specified delta.
    $weight = array_values($components)[$delta]->getWeight();
    $this->setComponent($new_component->setWeight($weight++));
    // Increase the weight of every subsequent component.
    foreach (array_slice($components, $delta) as $component) {
      $component->setWeight($weight++);
    }
    return $this;
  }
  
  /**
   * Wraps the layout plugin manager.
   *
   * @return \Drupal\Core\Layout\LayoutPluginManagerInterface
   *   The layout plugin manager.
   */
  protected function layoutPluginManager() {
    return \Drupal::service('plugin.manager.core.layout');
  }
  
  /**
   * Returns an array representation of the section.
   *
   * Only use this method if you are implementing custom storage for sections.
   *
   * @return array
   *   An array representation of the section component.
   */
  public function toArray() {
    return [
      'layout_id' => $this->getLayoutId(),
      'layout_settings' => $this->getLayoutSettings(),
      'components' => array_map(function (SectionComponent $component) {
        return $component->toArray();
      }, $this->getComponents()),
      'third_party_settings' => $this->thirdPartySettings,
    ];
  }
  
  /**
   * Creates an object from an array representation of the section.
   *
   * Only use this method if you are implementing custom storage for sections.
   *
   * @param array $section
   *   An array of section data in the format returned by ::toArray().
   *
   * @return static
   *   The section object.
   */
  public static function fromArray(array $section) {
    // Ensure expected array keys are present.
    $section += [
      'layout_id' => '',
      'layout_settings' => [],
      'components' => [],
      'third_party_settings' => [],
    ];
    return new static($section['layout_id'], $section['layout_settings'], array_map([
      SectionComponent::class,
      'fromArray',
    ], $section['components']), $section['third_party_settings']);
  }
  
  /**
   * Magic method: Implements a deep clone.
   */
  public function __clone() {
    foreach ($this->components as $uuid => $component) {
      $this->components[$uuid] = clone $component;
    }
  }
  
  /**
   * {@inheritdoc}
   */
  public function getThirdPartySetting($provider, $key, $default = NULL) {
    return $this->thirdPartySettings[$provider][$key] ?? $default;
  }
  
  /**
   * {@inheritdoc}
   */
  public function getThirdPartySettings($provider) {
    return $this->thirdPartySettings[$provider] ?? [];
  }
  
  /**
   * {@inheritdoc}
   */
  public function setThirdPartySetting($provider, $key, $value) {
    $this->thirdPartySettings[$provider][$key] = $value;
    return $this;
  }
  
  /**
   * {@inheritdoc}
   */
  public function unsetThirdPartySetting($provider, $key) {
    unset($this->thirdPartySettings[$provider][$key]);
    // If the third party is no longer storing any information, completely
    // remove the array holding the settings for this provider.
    if (empty($this->thirdPartySettings[$provider])) {
      unset($this->thirdPartySettings[$provider]);
    }
    return $this;
  }
  
  /**
   * {@inheritdoc}
   */
  public function getThirdPartyProviders() {
    return array_keys($this->thirdPartySettings);
  }
  
  /**
   * Wraps the context handler.
   *
   * @return \Drupal\Core\Plugin\Context\ContextHandlerInterface
   *   The context handler.
   */
  protected function contextHandler() {
    return \Drupal::service('context.handler');
  }

}

Members

Title Sort descending Modifiers Object type Summary Overriden Title
Section::$components protected property An array of components, keyed by UUID.
Section::$layoutId protected property The layout plugin ID.
Section::$layoutSettings protected property The layout plugin settings.
Section::$thirdPartySettings protected property Third party settings.
Section::appendComponent public function Appends a component to the end of a region.
Section::contextHandler protected function Wraps the context handler.
Section::fromArray public static function Creates an object from an array representation of the section.
Section::getComponent public function Gets the component for a given UUID.
Section::getComponents public function Returns the components of the section.
Section::getComponentsByRegion public function Gets the components for a specific region.
Section::getDefaultRegion public function Gets the default region.
Section::getLayout public function Gets the layout plugin for this section.
Section::getLayoutId public function Gets the layout plugin ID for this section.
Section::getLayoutSettings public function Gets the layout plugin settings for this section.
Section::getNextHighestWeight protected function Returns the next highest weight of the component in a region.
Section::getThirdPartyProviders public function Gets the list of third parties that store information. Overrides ThirdPartySettingsInterface::getThirdPartyProviders
Section::getThirdPartySetting public function Gets the value of a third-party setting. Overrides ThirdPartySettingsInterface::getThirdPartySetting
Section::getThirdPartySettings public function Gets all third-party settings of a given module. Overrides ThirdPartySettingsInterface::getThirdPartySettings
Section::insertAfterComponent public function Inserts a component after a specified existing component.
Section::insertComponent public function Inserts a component at a specified delta.
Section::layoutPluginManager protected function Wraps the layout plugin manager.
Section::removeComponent public function Removes a given component from a region.
Section::setComponent protected function Helper method to set a component.
Section::setLayoutSettings public function Sets the layout plugin settings for this section.
Section::setThirdPartySetting public function Sets the value of a third-party setting. Overrides ThirdPartySettingsInterface::setThirdPartySetting
Section::toArray public function Returns an array representation of the section.
Section::toRenderArray public function Returns the renderable array for this section.
Section::unsetThirdPartySetting public function Unsets a third-party setting. Overrides ThirdPartySettingsInterface::unsetThirdPartySetting
Section::__clone public function Magic method: Implements a deep clone.
Section::__construct public function Constructs a new Section.

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.