The Layout Plugin handbook pages are currently accurate for the API of the contrib module, once #2296423: Implement layout plugin type in core is committed it needs updating.

Proposed resolution

Remaining tasks

User interface changes

API changes

Data model changes


tim.plunkett created an issue. See original summary.

xjm’s picture

We might want to add a child page specifically on how to update from the contrib module to the core one.

jibran’s picture

Status: Postponed » Active

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.0-alpha1 will be released the week of January 30, 2017, which means new developments and disruptive changes should now be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

tim.plunkett’s picture

Meant to start writing docs today, but got bogged down in figuring out the new docs system (turns out it uses OG!) is a placeholder

HongPong’s picture

I have updated the documentation page for layout plugin to help with the 8.3.x transition:

Also note API documentation for layout_discovery now available:

tim.plunkett’s picture

Thanks @HongPong! Ideally that info would live here:

Manuel Garcia’s picture

I've updated with my findings - please review =)

  • Added Listing available layouts section
  • Added Instantiating a layout plugin section
  • Added Rendering a layout section

Also formatted the Getting the layout plugin manager section.

HongPong’s picture

@Manuel Garcia this is very good. @tim.plunkett I have updated these three pages to reflect all of this new situation and put a simplified version at the URL you flag. , ,

tim.plunkett’s picture

Status: Active » Fixed

The new docs are equal to or better than the old docs. Can still use improving, but this is enough for now.
Thanks @HongPong and @Manuel Garcia!

Manuel Garcia’s picture

We're missing the section on "Storing configuration for the selected layout" on

I've been messing with this, providing a layout with a configuration form, which shows up and saves fine using the field layout module. However when viewing a node, the twig file does not get the saved value, just the default value... so Im reluctant to put this as an example, can you guys see anything I'm missing?

Here is the layout class:

 * A very advanced custom layout.
 * @Layout(
 *   id = "layouts_tester_layout",
 *   label = @Translation("Layouts Tester Layout"),
 *   category = "Tester Layouts",
 *   description = @Translation("A testing layout for testing porpsues"),
 *   template = "templates/layouts_tester_layout",
 *   regions = {
 *     "main" = {
 *       "label" = @Translation("Main content"),
 *     }
 *   },
 *   type = "page",
 * )
class LayoutsTesterLayout extends LayoutDefault implements PluginFormInterface {

   * {@inheritdoc}
  public function defaultConfiguration() {
    return parent::defaultConfiguration() + [
      'background_colour' => '#111111',

   * {@inheritdoc}
  public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
    $configuration = $this->getConfiguration();
    $form['background_colour'] = [
      '#type' => 'color',
      '#title' => 'Backround colour',
      '#default_value' => $configuration['background_colour'],

    return $form;

   * {@inheritdoc}
  public function validateConfigurationForm(array &$form, FormStateInterface $form_state) {

   * {@inheritdoc}
  public function submitConfigurationForm(array &$form, FormStateInterface $form_state) {
    $this->setConfiguration(['background_colour' => $form_state->getValue('background_colour')]);


And the twig file:

  set classes = [
<div{{ attributes.addClass(classes) }} style="background-color: {{ settings.background_colour }}">

{{ content.main }}
tim.plunkett’s picture

submitConfigurationForm should use just $this->configuration['whatever'] = $whatever;, not $this->setConfiguration()

The rest looks okay, and mirrors what DS does. Can you open a separate issue to discuss this?

Manuel Garcia’s picture

Thank you that was it, it works fine now. Opened #2871717: Add saving Layout Plugin configuration handbook documentation for this

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.