diff -u b/core/modules/layout/lib/Drupal/layout/Config/BoundDisplayInterface.php b/core/modules/layout/lib/Drupal/layout/Config/BoundDisplayInterface.php --- b/core/modules/layout/lib/Drupal/layout/Config/BoundDisplayInterface.php +++ b/core/modules/layout/lib/Drupal/layout/Config/BoundDisplayInterface.php @@ -9,11 +9,11 @@ use Drupal\layout\Plugin\LayoutInterface; /** - * Interface for a Display object that is coupled to a specific layout plugin. + * Interface for a Display object that is coupled to a specific layout. * - * This display contains references both to block instances and a specific - * layout plugin. The blocks are assigned to the regions declared by that - * layout. Bound Displays are used to serve real pages at request time. + * Bound displays contains references both to block instances and a specific + * layout, and the blocks are assigned to specific regions in that layout. Bound + * displays are used to serve real pages at request time. * * @see \Drupal\layout\Config\DisplayInterface */ @@ -28,22 +28,19 @@ public function setLayout($layout_id); /** - * Returns display information for each block in the requested region. + * Returns the blocks in the requested region, ordered by weight. * * @param string $region * The region from which to return the set of blocks. * * @return array - * The same information as returned by - * \Drupal\layout\Config\DisplayInterface::getAllBlockInfo(), but only for - * blocks in the requested region, and ordered by block weight. - * - * @see \Drupal\layout\Config\DisplayInterface::getAllBlockInfo() + * The list of blocks, ordered by their weight within this display. Each + * value in the list is the configuration object name of the block. */ public function getSortedBlocksByRegion($region); /** - * Returns display information for each block, keyed by region and block. + * Returns this display's blocks, organized by region and ordered by weight. * * @return array * An array keyed by region name. For each region, the value is the same as diff -u b/core/modules/layout/lib/Drupal/layout/Config/DisplayBase.php b/core/modules/layout/lib/Drupal/layout/Config/DisplayBase.php --- b/core/modules/layout/lib/Drupal/layout/Config/DisplayBase.php +++ b/core/modules/layout/lib/Drupal/layout/Config/DisplayBase.php @@ -11,11 +11,9 @@ use Drupal\layout\Plugin\LayoutInterface; /** - * Configuration encapsulator that provides all the data needed by block-driven - * controllers to render a page. + * Base class for 'display' and 'unbound_display' configuration entities. * - * This is an abstract parent containing functionality shared by both Display - * and UnboundDisplay config objects. + * @see \Drupal\layout\Config\DisplayInterface */ abstract class DisplayBase extends ConfigEntityBase implements DisplayInterface { @@ -82,8 +80,6 @@ /** * Implements DisplayInterface::getAllBlockInfo(). - * - * @return array */ public function getAllBlockInfo() { return $this->blockInfo; @@ -92,11 +88,8 @@ /** * Implements DisplayInterface::mapBlocksToLayout(). * - * @todo this logic ought not be tightly coupled to this class. - * - * @param \Drupal\layout\Plugin\LayoutInterface $layout - * - * @return array + * @todo Decouple this implementation from this class, so that it could be + * more easily customized. */ public function mapBlocksToLayout(LayoutInterface $layout) { $types = array(); @@ -130,8 +123,6 @@ /** * Implements DisplayInterface::getAllRegionTypes(). - * - * @return array */ public function getAllRegionTypes() { $types = array(); diff -u b/core/modules/layout/lib/Drupal/layout/Config/DisplayInterface.php b/core/modules/layout/lib/Drupal/layout/Config/DisplayInterface.php --- b/core/modules/layout/lib/Drupal/layout/Config/DisplayInterface.php +++ b/core/modules/layout/lib/Drupal/layout/Config/DisplayInterface.php @@ -12,35 +12,59 @@ * Interface describing a Display configuration object. * * Displays are configuration that describe the placement of block instances - * in regions, as well as certain ways (for example, caching and visibility) of - * those block instances within those regions. + * in regions. Drupal includes two types of Display objects: + * - Bound displays include a reference to a specific layout, and each block is + * specified to display in a specific region of that layout. Bound displays + * are used to serve real pages at request time. + * - Unbound displays do not include a reference to any layout, and each block + * is assigned a region type, but not a specific region. Developers including + * default displays with their modules or distributions are encouraged to use + * unbound displays in order to minimize dependencies on specific layouts and + * allow site-specific configuration to dictate the layout. * - * Drupal ships with two major families of Display objects: + * This interface defines what is common to all displays, whether bound or + * unbound. * * @see \Drupal\layout\Config\BoundDisplayInterface * @see \Drupal\layout\Config\UnboundDisplayInterface - * */ interface DisplayInterface { /** - * Returns the config info about all blocks on this display. + * Returns the display-specific configuration of all blocks in this display. * - * There are two levels of configuration that are being captured here: the - * configuration for the block itself (i.e., config generated by a user saving - * the block's edit form), and configuration for how the particular block - * instance behaves in *this* display. The former is typically its own config - * object, and only a reference to that config key is stored directly on this - * object. The most important examples of the latter are the region in which - * the block is placed, and its weighting within the region. + * For each block that exists in Drupal (e.g., the "Who's Online" block), + * multiple "configured instances" can be created (e.g., a "Who's been online + * in the last 5 minutes" instance and a "Who's been online in the last 60 + * minutes" instance). Each configured instance can be referenced by multiple + * displays (e.g., by a "regular" page, by an administrative page, and within + * one or more dashboards). This function returns the block instances that + * have been added to this display. Each key of the returned array is the + * block instance's configuration object name, and config() may be called on + * it in order to retrieve the full configuration that is shared across all + * displays. For each key, the value is an array of display-specific + * configuration, primarily the 'region' and 'weight', and anything else that + * affects the placement of the block within the layout rather than only the + * contents of the block. * * @return array - * An array of block info, keyed on each block's config name. + * An array keyed on each block's configuration object name. Each value is + * an array of information that determines the placement of the block within + * a layout, including: + * - region: The region in which to display the block (for bound displays + * only). + * - region-type: The type of region that is most appropriate for the block. + * Usually one of 'header', 'footer', 'nav', 'content', 'aside', or + * 'system', though custom region types are also allowed. This is + * primarily specified by unbound displays, where specifying a specific + * region name is impossible, because different layouts come with + * different regions. + * - weight: Within a region, blocks are rendered from low to high weight. */ public function getAllBlockInfo(); /** - * Map the contained block info to the provided layout. + * Maps the contained block info to the provided layout. * * @param \Drupal\layout\Plugin\LayoutInterface $layout * diff -u b/core/modules/layout/lib/Drupal/layout/Config/UnboundDisplayInterface.php b/core/modules/layout/lib/Drupal/layout/Config/UnboundDisplayInterface.php --- b/core/modules/layout/lib/Drupal/layout/Config/UnboundDisplayInterface.php +++ b/core/modules/layout/lib/Drupal/layout/Config/UnboundDisplayInterface.php @@ -9,40 +9,38 @@ use Drupal\layout\Plugin\LayoutInterface; /** - * Interface for a Display that is not coupled with any layout plugin. + * Interface for a Display that is not coupled with any layout. * - * Unbound Displays contain references to blocks, but not to any particular - * layout plugin. Their primary use case is to express a set of relative block + * Unbound displays contain references to blocks, but not to any particular + * layout. Their primary use case is to express a set of relative block * placements without necessitating any particular layout be present. This * allows upstream (module and distribution) developers to express a visual - * composition of blocks without knowing anything about the layout plugins a + * composition of blocks without knowing anything about the layouts a * particular site has available. * * @see \Drupal\layout\Config\DisplayInterface */ interface UnboundDisplayInterface extends DisplayInterface { + /** - * Bind this UnboundDisplay to a particular display. + * Returns a bound display entity by binding a layout to this unbound display. * * This will DisplayInterface::mapBlocksToLayout() using the provided layout, * then create and return a new Display object with the output. This is just - * a factory - calling code is responsible for saving the + * a factory - calling code is responsible for saving the returned object. * * @param \Drupal\layout\Plugin\LayoutInterface $layout - * The layout plugin to which this config object should be bound. + * The desired layout. * * @param string $id - * The id that will be used to uniquely identify the created Display. It - * will be appended to the config prefix for Displays ("display", unless - * altered) to form the new Display's config address. + * The entity id to assign to the newly created entity. * * @param string $entity_type - * The type of entity to create. Must resolve to a class implementing - * BoundDisplayInterface. + * The type of entity to create. The PHP class for this entity type must + * implement \Drupal\layout\Config\BoundDisplayInterface. * - * @return \Drupal\layout\Plugin\Core\Entity\Display - * A Display object that has had the data from this config object mapped to - * the provided layout plugin. + * @return \Drupal\layout\Config\BoundDisplayInterface + * The newly created entity. */ public function generateDisplay(LayoutInterface $layout, $id, $entity_type = 'display'); } diff -u b/core/modules/layout/lib/Drupal/layout/Plugin/Core/Entity/Display.php b/core/modules/layout/lib/Drupal/layout/Plugin/Core/Entity/Display.php --- b/core/modules/layout/lib/Drupal/layout/Plugin/Core/Entity/Display.php +++ b/core/modules/layout/lib/Drupal/layout/Plugin/Core/Entity/Display.php @@ -15,8 +15,7 @@ use Drupal\Core\Annotation\Translation; /** - * Configuration encapsulator that provides all the data needed by block-driven - * controllers to render a page. + * Defines the display entity. * * @Plugin( * id = "display", @@ -31,6 +30,7 @@ * ) */ class Display extends DisplayBase implements BoundDisplayInterface { + /** * A two-level array expressing block ordering within regions. * @@ -48,11 +48,11 @@ protected $blocksInRegions; /** - * The layout plugin instance being used to serve this page. + * The layout instance being used to serve this page. * * @var \Drupal\layout\Plugin\LayoutInterface */ - protected $layoutPlugin; + protected $layoutInstance; /** * The name of the layout plugin to use. @@ -62,21 +62,15 @@ public $layout; /** - * An array of settings to be coupled with the layout plugin to create a - * layout plugin instance. + * The settings with which to instantiate the layout plugin. * * @var array - * - * @todo we might possibly want to separate this into its own config object */ public $layoutSettings = array(); /** * Implements BoundDisplayInterface::getSortedBlocksByRegion(). * - * @param string $region - * - * @return array * @throws \Exception */ public function getSortedBlocksByRegion($region) { @@ -93,8 +87,6 @@ /** * Implements BoundDisplayInterface::getAllSortedBlocks(). - * - * @return array|mixed */ public function getAllSortedBlocks() { if ($this->blocksInRegions === NULL) { @@ -131,8 +123,6 @@ /** * Implements BoundDisplayInterface::remapToLayout(). - * - * @param \Drupal\layout\Plugin\LayoutInterface $layout */ public function remapToLayout(LayoutInterface $layout) { $this->blockInfo = $this->mapBlocksToLayout($layout); @@ -148,7 +138,7 @@ public function setLayout($plugin_id) { // @todo verification? $this->layout = $plugin_id; - $this->layoutPlugin = NULL; + $this->layoutInstance = NULL; $this->blocksInRegions = NULL; } @@ -177,15 +167,20 @@ } + /** + * Returns the instantiated layout object. + * + * @throws \Exception + */ public function getLayoutInstance() { - if ($this->layoutPlugin === NULL) { + if ($this->layoutInstance === NULL) { if (empty($this->layout)) { throw new \Exception(sprintf('Display "%id" had no layout plugin attached.', array('%id' => $this->id())), E_RECOVERABLE_ERROR); } - $this->layoutPlugin = layout_manager()->createInstance($this->layout, $this->layoutSettings); + $this->layoutInstance = layout_manager()->createInstance($this->layout, $this->layoutSettings); // @todo add handling for remapping if the layout could not be found } - return $this->layoutPlugin; + return $this->layoutInstance; } } diff -u b/core/modules/layout/lib/Drupal/layout/Plugin/Core/Entity/UnboundDisplay.php b/core/modules/layout/lib/Drupal/layout/Plugin/Core/Entity/UnboundDisplay.php --- b/core/modules/layout/lib/Drupal/layout/Plugin/Core/Entity/UnboundDisplay.php +++ b/core/modules/layout/lib/Drupal/layout/Plugin/Core/Entity/UnboundDisplay.php @@ -15,11 +15,10 @@ use Drupal\Core\Annotation\Translation; /** - * Configuration encapsulator that provides all the data needed by block-driven - * controllers to render a page. + * Defines the unbound_display entity. * * Unbound displays contain blocks that are not 'bound' to a specific layout, - * and their contained blocks are mapped only to region types, not real regions. + * and their contained blocks are mapped only to region types, not regions. * * @Plugin( * id = "unbound_display",