3 namespace Drupal\layout_builder;
6 * Provides a domain object for layout sections.
8 * A section consists of three parts:
9 * - The layout plugin ID for the layout applied to the section (for example,
11 * - An array of settings for the layout plugin.
12 * - An array of components that can be rendered in the section.
15 * Layout Builder is currently experimental and should only be leveraged by
16 * experimental modules and development releases of contributed modules.
17 * See https://www.drupal.org/core/experimental for more information.
19 * @see \Drupal\Core\Layout\LayoutDefinition
20 * @see \Drupal\layout_builder\SectionComponent
22 * @todo Determine whether an interface will be provided for this in
23 * https://www.drupal.org/project/drupal/issues/2930334.
28 * The layout plugin ID.
35 * The layout plugin settings.
39 protected $layoutSettings = [];
42 * An array of components, keyed by UUID.
44 * @var \Drupal\layout_builder\SectionComponent[]
46 protected $components = [];
49 * Constructs a new Section.
51 * @param string $layout_id
52 * The layout plugin ID.
53 * @param array $layout_settings
54 * (optional) The layout plugin settings.
55 * @param \Drupal\layout_builder\SectionComponent[] $components
56 * (optional) The components.
58 public function __construct($layout_id, array $layout_settings = [], array $components = []) {
59 $this->layoutId = $layout_id;
60 $this->layoutSettings = $layout_settings;
61 foreach ($components as $component) {
62 $this->setComponent($component);
67 * Returns the renderable array for this section.
69 * @param \Drupal\Core\Plugin\Context\ContextInterface[] $contexts
70 * An array of available contexts.
71 * @param bool $in_preview
72 * TRUE if the section is being previewed, FALSE otherwise.
75 * A renderable array representing the content of the section.
77 public function toRenderArray(array $contexts = [], $in_preview = FALSE) {
79 foreach ($this->getComponents() as $component) {
80 if ($output = $component->toRenderArray($contexts, $in_preview)) {
81 $regions[$component->getRegion()][$component->getUuid()] = $output;
85 return $this->getLayout()->build($regions);
89 * Gets the layout plugin for this section.
91 * @return \Drupal\Core\Layout\LayoutInterface
94 public function getLayout() {
95 return $this->layoutPluginManager()->createInstance($this->getLayoutId(), $this->getLayoutSettings());
99 * Gets the layout plugin ID for this section.
102 * The layout plugin ID.
105 * This method should only be used by code responsible for storing the data.
107 public function getLayoutId() {
108 return $this->layoutId;
112 * Gets the layout plugin settings for this section.
115 * The layout plugin settings.
118 * This method should only be used by code responsible for storing the data.
120 public function getLayoutSettings() {
121 return $this->layoutSettings;
125 * Sets the layout plugin settings for this section.
127 * @param mixed[] $layout_settings
128 * The layout plugin settings.
132 public function setLayoutSettings(array $layout_settings) {
133 $this->layoutSettings = $layout_settings;
138 * Gets the default region.
141 * The machine-readable name of the default region.
143 public function getDefaultRegion() {
144 return $this->layoutPluginManager()->getDefinition($this->getLayoutId())->getDefaultRegion();
148 * Returns the components of the section.
150 * @return \Drupal\layout_builder\SectionComponent[]
153 public function getComponents() {
154 return $this->components;
158 * Gets the component for a given UUID.
160 * @param string $uuid
161 * The UUID of the component to retrieve.
163 * @return \Drupal\layout_builder\SectionComponent
166 * @throws \InvalidArgumentException
167 * Thrown when the expected UUID does not exist.
169 public function getComponent($uuid) {
170 if (!isset($this->components[$uuid])) {
171 throw new \InvalidArgumentException(sprintf('Invalid UUID "%s"', $uuid));
174 return $this->components[$uuid];
178 * Helper method to set a component.
180 * @param \Drupal\layout_builder\SectionComponent $component
185 protected function setComponent(SectionComponent $component) {
186 $this->components[$component->getUuid()] = $component;
191 * Removes a given component from a region.
193 * @param string $uuid
194 * The UUID of the component to remove.
198 public function removeComponent($uuid) {
199 unset($this->components[$uuid]);
204 * Appends a component to the end of a region.
206 * @param \Drupal\layout_builder\SectionComponent $component
207 * The component being appended.
211 public function appendComponent(SectionComponent $component) {
212 $component->setWeight($this->getNextHighestWeight($component->getRegion()));
213 $this->setComponent($component);
218 * Returns the next highest weight of the component in a region.
220 * @param string $region
224 * A number higher than the highest weight of the component in the region.
226 protected function getNextHighestWeight($region) {
227 $components = $this->getComponentsByRegion($region);
228 $weights = array_map(function (SectionComponent $component) {
229 return $component->getWeight();
231 return $weights ? max($weights) + 1 : 0;
235 * Gets the components for a specific region.
237 * @param string $region
240 * @return \Drupal\layout_builder\SectionComponent[]
241 * An array of components in the specified region, sorted by weight.
243 protected function getComponentsByRegion($region) {
244 $components = array_filter($this->getComponents(), function (SectionComponent $component) use ($region) {
245 return $component->getRegion() === $region;
247 uasort($components, function (SectionComponent $a, SectionComponent $b) {
248 return $a->getWeight() > $b->getWeight() ? 1 : -1;
254 * Inserts a component after a specified existing component.
256 * @param string $preceding_uuid
257 * The UUID of the existing component to insert after.
258 * @param \Drupal\layout_builder\SectionComponent $component
259 * The component being inserted.
263 * @throws \InvalidArgumentException
264 * Thrown when the expected UUID does not exist.
266 public function insertAfterComponent($preceding_uuid, SectionComponent $component) {
267 // Find the delta of the specified UUID.
268 $uuids = array_keys($this->getComponentsByRegion($component->getRegion()));
269 $delta = array_search($preceding_uuid, $uuids, TRUE);
270 if ($delta === FALSE) {
271 throw new \InvalidArgumentException(sprintf('Invalid preceding UUID "%s"', $preceding_uuid));
273 return $this->insertComponent($delta + 1, $component);
277 * Inserts a component at a specified delta.
280 * The zero-based delta in which to insert the component.
281 * @param \Drupal\layout_builder\SectionComponent $new_component
282 * The component being inserted.
286 * @throws \OutOfBoundsException
287 * Thrown when the specified delta is invalid.
289 public function insertComponent($delta, SectionComponent $new_component) {
290 $components = $this->getComponentsByRegion($new_component->getRegion());
291 $count = count($components);
292 if ($delta > $count) {
293 throw new \OutOfBoundsException(sprintf('Invalid delta "%s" for the "%s" component', $delta, $new_component->getUuid()));
296 // If the delta is the end of the list, append the component instead.
297 if ($delta === $count) {
298 return $this->appendComponent($new_component);
301 // Find the weight of the component that exists at the specified delta.
302 $weight = array_values($components)[$delta]->getWeight();
303 $this->setComponent($new_component->setWeight($weight++));
305 // Increase the weight of every subsequent component.
306 foreach (array_slice($components, $delta) as $component) {
307 $component->setWeight($weight++);
313 * Wraps the layout plugin manager.
315 * @return \Drupal\Core\Layout\LayoutPluginManagerInterface
316 * The layout plugin manager.
318 protected function layoutPluginManager() {
319 return \Drupal::service('plugin.manager.core.layout');
323 * Returns an array representation of the section.
325 * Only use this method if you are implementing custom storage for sections.
328 * An array representation of the section component.
330 public function toArray() {
332 'layout_id' => $this->getLayoutId(),
333 'layout_settings' => $this->getLayoutSettings(),
334 'components' => array_map(function (SectionComponent $component) {
335 return $component->toArray();
336 }, $this->getComponents()),
341 * Creates an object from an array representation of the section.
343 * Only use this method if you are implementing custom storage for sections.
345 * @param array $section
346 * An array of section data in the format returned by ::toArray().
349 * The section object.
351 public static function fromArray(array $section) {
353 $section['layout_id'],
354 $section['layout_settings'],
355 array_map([SectionComponent::class, 'fromArray'], $section['components'])