>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #2811175. --> Reported by: [tim.plunkett](https://www.drupal.org/user/241634) >>> <h3>Background</h3> <p>There are several places in Drupal where elements can be arranged to control their placement.</p> <ul> <li>Themes have regions, which contain blocks.</li> <li>Content forms have form elements.</li> <li>Content has fields.</li> </ul> <p>Contrib modules such as Display Suite and Panels can be used to enhance or replace these systems.</p> <h3>Problem</h3> <ul> <li>Each of the above have their own mechanisms for laying out their elements. They are separate systems, with varying levels of flexibility.</li> <li>In core, content view and content forms have no means of altering their layout in the UI, just rearranging the fields by weight.</li> <li>Regions of a theme can be customized, but this is done in files (THEMENAME.info.yml and page.html.twig), and is global for that theme.</li> </ul> <p>Some contributed modules aim to solve this problem, but they also provide many other features that can be overwhelming compared to the task of simply altering a layout.</p> <h3>Proposed resolution</h3> <ol> <li>Bring the "Layout Plugin" API into core. This will be used by all core layouting systems, and can continue to be used by contrib.</li> <li>Enhance the Field UI to allow content and their forms to have customizable layouts. This mimics the basic functionality of Panelizer and Display Suite.</li> <li>Allow themes to provide layouts.</li> <li>Provide a means to have different theme layouts for different parts of the site.</li> </ol> <p>There is currently discussion over whether the Layout API should live as an experimental module or as an experimental subsystem (or a combination of both).<br> See <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2296423" title="Status: Closed (fixed)">#2296423: Implement layout plugin type in core</a></span> and later.</p> <p>Documentation for transitioning from layout_plugin contrib module to layout_discovery: <a href="https://www.drupal.org/node/2619128">https://www.drupal.org/node/2619128</a></p> <p>API documentation for layout_discovery now available: <a href="https://api.drupal.org/api/drupal/8.3.x/search/layout_discovery">https://api.drupal.org/api/drupal/8.3.x/search/layout_discovery</a></p> <h3>Process and where to find it</h3> <p>The tag for these issues is <a href="https://www.drupal.org/project/issues/search?status%5B%5D=Open&amp;issue_tags=Blocks-Layouts">Blocks-Layouts</a>.</p> <h3>Proposal roadmap</h3> <h4>Must have</h4> <h5>Remaining</h5> <ul> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-6"><a href="https://www.drupal.org/project/drupal/issues/2919372" title="Status: Closed (works as designed)">#2919372: Layouts do not respect RTL</a></span></li> </ul> <h5>Completed</h5> <ol> <li>The first step is to add the layout plugin API to core experimentally:<br> <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2296423" title="Status: Closed (fixed)">#2296423: Implement layout plugin type in core</a></span></li> <li>To validate the implementation, an experimental core implementation should be added and ideally reach beta, one or both of: <ul> <li>Content layouts: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2796173" title="Status: Closed (fixed)">#2796173: Add experimental Field Layout module to allow entity view/form modes to switch between layouts</a></span> (the initial prototype for <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-1"><a href="https://www.drupal.org/project/drupal/issues/2795833" title="Status: Active">#2795833: [plan] Add layouts to entity displays (both form and view)</a></span>)</li> <li>Full page layouts: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-17"><a href="https://www.drupal.org/project/drupal/issues/2811179" title="Status: Closed (outdated)">#2811179: Allow themes to provide Layout API integration</a></span></li> </ul> </li> <li>For the layout plugin API to be considered stable, it also needs to be validated by (ideally) beta contrib implementations, at a minimum: <ul> <li>Panels: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/panels/issues/2821226" title="Status: Closed (fixed)">#2821226: Update Panels for layout_plugin in core</a></span></li> <li>Display Suite: DS already has an 8.x-3.x development branch compatible with this API! <a href="http://cgit.drupalcode.org/ds/tree/ds.info.yml?h=8.x-3.x#n8">http://cgit.drupalcode.org/ds/tree/ds.info.yml?h=8.x-3.x#n8</a></li> </ul> <p>Additionally, we need to stabilize the layout plugin API in a way that allows these modules (and sites using them) to upgrade from the layout_plugin contrib module to the core module once it is ready to be stable:<br> <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2833976" title="Status: Closed (fixed)">#2833976: How Panels, Display suite, Layout Plugin, Layout Discovery and core get to a stable layout plugin in core</a></span> </p></li> </ol> <p>Other must-haves:</p> <ul> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2824667" title="Status: Closed (fixed)">#2824667: Update Layout Plugin handbook documentation</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2852608" title="Status: Closed (fixed)">#2852608: Review layout CSS and markup</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2834025" title="Status: Closed (fixed)">#2834025: Mark Layout Discovery as a stable module</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-5"><a href="https://www.drupal.org/project/drupal/issues/2822758" title="Status: Closed (won't fix)">#2822758: Introduce a way to distinguish between different types of layouts</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-3"><a href="https://www.drupal.org/project/drupal/issues/2834019" title="Status: Closed (duplicate)">#2834019: Remove the "layout__" prefixing of theme hooks</a></span></li> </ul> <h4>Should have</h4> <ul> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2818653" title="Status: Closed (fixed)">#2818653: Allow object-based plugin definitions to be processed in DefaultPluginManager::findDefinitions()</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2821189" title="Status: Closed (fixed)">#2821189: Allow object-based plugin definitions to be processed in DerivativeDiscoveryDecorator</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2821191" title="Status: Closed (fixed)">#2821191: Allow object-based plugin definitions to be processed in PluginDependencyTrait</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2822752" title="Status: Closed (fixed)">#2822752: Allow object-based plugin definitions to be created by non-annotated discovery</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2824655" title="Status: Closed (fixed)">#2824655: Plugin definitions should store their class in a consistent manner (without leading slashes)</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-13"><a href="https://www.drupal.org/project/drupal/issues/2824890" title="Status: Needs work">#2824890: Convert uasort to array_multisort in \Drupal\Core\Plugin\CategorizingPluginManagerTrait::getSortedDefinitions()</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2660124" title="Status: Closed (fixed)">#2660124: Dynamically build layout icons based on well formed config</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-1"><a href="https://www.drupal.org/project/drupal/issues/2848549" title="Status: Active">#2848549: Refine the layout selection UI</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-1"><a href="https://www.drupal.org/project/field_layout/issues/2796877" title="Status: Active">#2796877: Devise a mechanism for mapping old regions to new ones when moving between layouts</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-3"><a href="https://www.drupal.org/project/drupal/issues/2860903" title="Status: Closed (duplicate)">#2860903: Provide a mechanism for a module to restrict the allowed layouts it can use</a></span></li> </ul> <h4>Could have</h4> <ul> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-13"><a href="https://www.drupal.org/project/drupal/issues/1787942" title="Status: Needs work">#1787942: Allow assigning layouts to pages</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-13"><a href="https://www.drupal.org/project/drupal/issues/2833347" title="Status: Needs work">#2833347: Allow experimental modules to rely on \Drupal\Core\ namespaced classes that are only loadable when the module is enabled </a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-6"><a href="https://www.drupal.org/project/drupal/issues/2834023" title="Status: Closed (works as designed)">#2834023: Discuss service ID and config schema naming for Layouts</a></span></li> </ul> <h3>Not in scope</h3> <ul> <li>Arbitrary page creation (like Page Manager)</li> <li>Layout editing (flexible layouts builder)</li> </ul> <h4>Contributed projects</h4> <p>Panels, Panels Everywhere, Page Manager, Panelizer, Mini panels, Display Suite, Context</p> <h3>Team and resources</h3> <ul> <li>Developer/Architect: <a href="https://www.drupal.org/u/timplunkett">@tim.plunkett</a> (funded by Acquia's Office of the CTO)</li> <li>Developer/Designer: <a href="https://www.drupal.org/u/dyannenova">@ DyanneNova </a> (funded by Acquia's Office of the CTO)</li> </ul> <h4>Signoffs needed</h4> <ul> <li>Framework manager</li> <li>Usability topic maintainers</li> <li>Accessibility topic maintainers</li> </ul> <h4>Signoffs given</h4> <ul> <li>Release manager: xjm in #22</li> <li>Product manager: yoroy in #59</li> </ul> <p>No other explicit signoffs have been given, but the initial discussion happened at DrupalCon New Orleans among the following people:<br> G&aacute;bor Hojtsy, xjm, japerry, tim.plunkett, Bojhan, DyanneNova, stevector, dsnopek, ted.bowman, alexpott, yoroy, dobe, hestenet, Crell, swentel, aspilicious</p> > Related issue: [Issue #2795833](https://www.drupal.org/node/2795833) > Related issue: [Issue #2905922](https://www.drupal.org/node/2905922)