Issue #2296423 by tim.plunkett, dsnopek, swentel, Manuel Garcia, tedbow,...

Issue #2296423 by tim.plunkett, dsnopek, swentel, Manuel Garcia, tedbow, alexpott, xjm, andypost, dawehner, effulgentsia, Berdir, jhedstrom, catch, benjy, jibran, Wim Leers, tstoeckler, larowlan, webchick: Implement layout plugin type in core

core/composer.json

@@ -105,6 +105,7 @@
         "drupal/image": "self.version",
         "drupal/inline_form_errors": "self.version",
         "drupal/language": "self.version",
+        "drupal/layout_discovery": "self.version",
         "drupal/link": "self.version",
         "drupal/locale": "self.version",
         "drupal/minimal": "self.version",

core/config/schema/core.data_types.schema.yml

@@ -361,6 +361,13 @@ display_variant.plugin:
       type: string
       label: 'UUID'
 
+layout_plugin.settings:
+  type: mapping
+  label: 'Layout settings'
+
+layout_plugin.settings.*:
+  type: layout_plugin.settings
+
 base_entity_reference_field_settings:
   type: mapping
   mapping:

core/core.api.php

@@ -2178,6 +2178,17 @@ function hook_display_variant_plugin_alter(array &$definitions) {
   $definitions['full_page']['admin_label'] = t('Block layout');
 }
 
+/**
+ * Allow modules to alter layout plugin definitions.
+ *
+ * @param \Drupal\Core\Layout\LayoutDefinition[] $definitions
+ *   The array of layout definitions, keyed by plugin ID.
+ */
+function hook_layout_alter(&$definitions) {
+  // Remove a layout.
+  unset($definitions['twocol']);
+}
+
 /**
  * Flush all persistent and static caches.
  *

core/lib/Drupal/Core/Layout/Annotation/Layout.php

+<?php
+
+namespace Drupal\Core\Layout\Annotation;
+
+use Drupal\Component\Annotation\Plugin;
+use Drupal\Core\Layout\LayoutDefault;
+use Drupal\Core\Layout\LayoutDefinition;
+
+/**
+ * Defines a Layout annotation object.
+ *
+ * Layouts are used to define a list of regions and then output render arrays
+ * in each of the regions, usually using a template.
+ *
+ * Plugin namespace: Plugin\Layout
+ *
+ * @internal
+ *   The layout system is currently experimental and should only be leveraged by
+ *   experimental modules and development releases of contributed modules.
+ *   See https://www.drupal.org/core/experimental for more information.
+ *
+ * @see \Drupal\Core\Layout\LayoutInterface
+ * @see \Drupal\Core\Layout\LayoutDefault
+ * @see \Drupal\Core\Layout\LayoutPluginManager
+ * @see plugin_api
+ *
+ * @Annotation
+ */
+class Layout extends Plugin {
+
+  /**
+   * The plugin ID.
+   *
+   * @var string
+   */
+  public $id;
+
+  /**
+   * The human-readable name.
+   *
+   * @var string
+   *
+   * @ingroup plugin_translatable
+   */
+  public $label;
+
+  /**
+   * An optional description for advanced layouts.
+   *
+   * Sometimes layouts are so complex that the name is insufficient to describe
+   * a layout such that a visually impaired administrator could layout a page
+   * for a non-visually impaired audience. If specified, it will provide a
+   * description that is used for accessibility purposes.
+   *
+   * @var string
+   *
+   * @ingroup plugin_translatable
+   */
+  public $description;
+
+  /**
+   * The human-readable category.
+   *
+   * @var string
+   *
+   * @see \Drupal\Component\Plugin\CategorizingPluginManagerInterface
+   *
+   * @ingroup plugin_translatable
+   */
+  public $category;
+
+  /**
+   * The template file to render this layout (relative to the 'path' given).
+   *
+   * If specified, then the layout_discovery module will register the template
+   * with hook_theme() and the module or theme registering this layout does not
+   * need to do it.
+   *
+   * @var string optional
+   *
+   * @see hook_theme()
+   */
+  public $template;
+
+  /**
+   * The theme hook used to render this layout.
+   *
+   * If specified, it's assumed that the module or theme registering this layout
+   * will also register the theme hook with hook_theme() itself. This is
+   * mutually exclusive with 'template' - you can't specify both.
+   *
+   * @var string optional
+   *
+   * @see hook_theme()
+   */
+  public $theme_hook = 'layout';
+
+  /**
+   * Path (relative to the module or theme) to resources like icon or template.
+   *
+   * @var string optional
+   */
+  public $path;
+
+  /**
+   * The asset library.
+   *
+   * @var string optional
+   */
+  public $library;
+
+  /**
+   * The path to the preview image (relative to the 'path' given).
+   *
+   * @var string optional
+   */
+  public $icon;
+
+  /**
+   * An associative array of regions in this layout.
+   *
+   * The key of the array is the machine name of the region, and the value is
+   * an associative array with the following keys:
+   * - label: (string) The human-readable name of the region.
+   *
+   * Any remaining keys may have special meaning for the given layout plugin,
+   * but are undefined here.
+   *
+   * @var array
+   */
+  public $regions = [];
+
+  /**
+   * The default region.
+   *
+   * @var string
+   */
+  public $default_region;
+
+  /**
+   * The layout plugin class.
+   *
+   * This default value is used for plugins defined in layouts.yml that do not
+   * specify a class themselves.
+   *
+   * @var string
+   */
+  public $class = LayoutDefault::class;
+
+  /**
+   * {@inheritdoc}
+   */
+  public function get() {
+    return new LayoutDefinition($this->definition);
+  }
+
+}

core/lib/Drupal/Core/Layout/DerivablePluginDefinitionInterface.php

+<?php
+
+namespace Drupal\Core\Layout;
+
+use Drupal\Component\Plugin\Definition\PluginDefinitionInterface;
+
+/**
+ * Provides an interface for a derivable plugin definition.
+ *
+ * @see \Drupal\Component\Plugin\Derivative\DeriverInterface
+ * @see \Drupal\Core\Layout\ObjectDefinitionContainerDerivativeDiscoveryDecorator
+ *
+ * @internal
+ *   The layout system is currently experimental and should only be leveraged by
+ *   experimental modules and development releases of contributed modules.
+ *   See https://www.drupal.org/core/experimental for more information.
+ *
+ * @todo Move into \Drupal\Component\Plugin\Definition in
+ *   https://www.drupal.org/node/2821189.
+ */
+interface DerivablePluginDefinitionInterface extends PluginDefinitionInterface {
+
+  /**
+   * Gets the name of the deriver of this plugin definition, if it exists.
+   *
+   * @return string|null
+   *   Either the deriver class name, or NULL if the plugin is not derived.
+   */
+  public function getDeriver();
+
+  /**
+   * Sets the deriver of this plugin definition.
+   *
+   * @param string|null $deriver
+   *   Either the name of a class that implements
+   *   \Drupal\Component\Plugin\Derivative\DeriverInterface, or NULL.
+   *
+   * @return $this
+   */
+  public function setDeriver($deriver);
+
+}

core/lib/Drupal/Core/Layout/LayoutDefault.php

+<?php
+
+namespace Drupal\Core\Layout;
+
+use Drupal\Component\Utility\NestedArray;
+use Drupal\Core\Plugin\PluginBase;
+
+/**
+ * Provides a default class for Layout plugins.
+ *
+ * @internal
+ *   The layout system is currently experimental and should only be leveraged by
+ *   experimental modules and development releases of contributed modules.
+ *   See https://www.drupal.org/core/experimental for more information.
+ */
+class LayoutDefault extends PluginBase implements LayoutInterface {
+
+  /**
+   * The layout definition.
+   *
+   * @var \Drupal\Core\Layout\LayoutDefinition
+   */
+  protected $pluginDefinition;
+
+  /**
+   * {@inheritdoc}
+   */
+  public function __construct(array $configuration, $plugin_id, $plugin_definition) {
+    parent::__construct($configuration, $plugin_id, $plugin_definition);
+    $this->setConfiguration($configuration);
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function build(array $regions) {
+    $build = array_intersect_key($regions, $this->pluginDefinition->getRegions());
+    $build['#settings'] = $this->getConfiguration();
+    $build['#layout'] = $this->pluginDefinition;
+    $build['#theme'] = $this->pluginDefinition->getThemeHook();
+    if ($library = $this->pluginDefinition->getLibrary()) {
+      $build['#attached']['library'][] = $library;
+    }
+    return $build;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getConfiguration() {
+    return $this->configuration;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function setConfiguration(array $configuration) {
+    $this->configuration = NestedArray::mergeDeep($this->defaultConfiguration(), $configuration);
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function defaultConfiguration() {
+    return [];
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function calculateDependencies() {
+    return [];
+  }
+
+  /**
+   * {@inheritdoc}
+   *
+   * @return \Drupal\Core\Layout\LayoutDefinition
+   */
+  public function getPluginDefinition() {
+    return parent::getPluginDefinition();
+  }
+
+}

core/lib/Drupal/Core/Layout/LayoutDefinition.php

+<?php
+
+namespace Drupal\Core\Layout;
+
+use Drupal\Component\Plugin\Definition\PluginDefinitionInterface;
+
+/**
+ * Provides an implementation of a layout definition and its metadata.
+ *
+ * @internal
+ *   The layout system is currently experimental and should only be leveraged by
+ *   experimental modules and development releases of contributed modules.
+ *   See https://www.drupal.org/core/experimental for more information.
+ */
+class LayoutDefinition implements PluginDefinitionInterface, DerivablePluginDefinitionInterface {
+
+  /**
+   * The plugin ID.
+   *
+   * @var string
+   */
+  protected $id;
+
+  /**
+   * The name of the provider of this layout definition.
+   *
+   * @todo Make protected after https://www.drupal.org/node/2818653.
+   *
+   * @var string
+   */
+  public $provider;
+
+  /**
+   * The name of the deriver of this layout definition, if any.
+   *
+   * @var string|null
+   */
+  protected $deriver;
+
+  /**
+   * The dependencies of this layout definition.
+   *
+   * @todo Make protected after https://www.drupal.org/node/2821191.
+   *
+   * @var array
+   */
+  public $config_dependencies;
+
+  /**
+   * The human-readable name.
+   *
+   * @var string
+   */
+  protected $label;
+
+  /**
+   * An optional description for advanced layouts.
+   *
+   * @var string
+   */
+  protected $description;
+
+  /**
+   * The human-readable category.
+   *
+   * @var string
+   */
+  protected $category;
+
+  /**
+   * The template file to render this layout (relative to the 'path' given).
+   *
+   * @var string|null
+   */
+  protected $template;
+
+  /**
+   * The path to the template.
+   *
+   * @var string
+   */
+  protected $templatePath;
+
+  /**
+   * The theme hook used to render this layout.
+   *
+   * @var string|null
+   */
+  protected $theme_hook;
+
+  /**
+   * Path (relative to the module or theme) to resources like icon or template.
+   *
+   * @var string
+   */
+  protected $path;
+
+  /**
+   * The asset library.
+   *
+   * @var string|null
+   */
+  protected $library;
+
+  /**
+   * The path to the preview image.
+   *
+   * @var string
+   */
+  protected $icon;
+
+  /**
+   * An associative array of regions in this layout.
+   *
+   * The key of the array is the machine name of the region, and the value is
+   * an associative array with the following keys:
+   * - label: (string) The human-readable name of the region.
+   *
+   * Any remaining keys may have special meaning for the given layout plugin,
+   * but are undefined here.
+   *
+   * @var array
+   */
+  protected $regions = [];
+
+  /**
+   * The default region.
+   *
+   * @var string
+   */
+  protected $default_region;
+
+  /**
+   * The name of the layout class.
+   *
+   * @var string
+   */
+  protected $class;
+
+  /**
+   * Any additional properties and values.
+   *
+   * @var array
+   */
+  protected $additional = [];
+
+  /**
+   * LayoutDefinition constructor.
+   *
+   * @param array $definition
+   *   An array of values from the annotation.
+   */
+  public function __construct(array $definition) {
+    foreach ($definition as $property => $value) {
+      $this->set($property, $value);
+    }
+  }
+
+  /**
+   * Gets any arbitrary property.
+   *
+   * @param string $property
+   *   The property to retrieve.
+   *
+   * @return mixed
+   *   The value for that property, or NULL if the property does not exist.
+   */
+  public function get($property) {
+    if (property_exists($this, $property)) {
+      $value = isset($this->{$property}) ? $this->{$property} : NULL;
+    }
+    else {
+      $value = isset($this->additional[$property]) ? $this->additional[$property] : NULL;
+    }
+    return $value;
+  }
+
+  /**
+   * Sets a value to an arbitrary property.
+   *
+   * @param string $property
+   *   The property to use for the value.
+   * @param mixed $value
+   *   The value to set.
+   *
+   * @return $this
+   */
+  public function set($property, $value) {
+    if (property_exists($this, $property)) {
+      $this->{$property} = $value;
+    }
+    else {
+      $this->additional[$property] = $value;
+    }
+    return $this;
+  }
+
+  /**
+   * Gets the unique identifier of the layout definition.
+   *
+   * @return string
+   *   The unique identifier of the layout definition.
+   */
+  public function id() {
+    return $this->id;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getClass() {
+    return $this->class;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function setClass($class) {
+    $this->class = $class;
+    return $this;
+  }
+
+  /**
+   * Gets the human-readable name of the layout definition.
+   *
+   * @return string|\Drupal\Core\StringTranslation\TranslatableMarkup
+   *   The human-readable name of the layout definition.
+   */
+  public function getLabel() {
+    return $this->label;
+  }
+
+  /**
+   * Sets the human-readable name of the layout definition.
+   *
+   * @param string|\Drupal\Core\StringTranslation\TranslatableMarkup $label
+   *   The human-readable name of the layout definition.
+   *
+   * @return $this
+   */
+  public function setLabel($label) {
+    $this->label = $label;
+    return $this;
+  }
+
+  /**
+   * Gets the description of the layout definition.
+   *
+   * @return string|\Drupal\Core\StringTranslation\TranslatableMarkup
+   *   The description of the layout definition.
+   */
+  public function getDescription() {
+    return $this->description;
+  }
+
+  /**
+   * Sets the description of the layout definition.
+   *
+   * @param string|\Drupal\Core\StringTranslation\TranslatableMarkup $description
+   *   The description of the layout definition.
+   *
+   * @return $this
+   */
+  public function setDescription($description) {
+    $this->description = $description;
+    return $this;
+  }
+
+  /**
+   * Gets the human-readable category of the layout definition.
+   *
+   * @return string|\Drupal\Core\StringTranslation\TranslatableMarkup
+   *   The human-readable category of the layout definition.
+   */
+  public function getCategory() {
+    return $this->category;
+  }
+