Implement "display renderer" plugin type (now called "display builder")

@mglaman: Thanks for picking this up! All the boilerplate looks good, this is a good start. :-)

However, I think architecturally the model is inverted. IMO, the Renderer's job is to prepare the content of the regions before they go to the Layout. So, DisplayVariant asks the Renderer to prepare the regions and then passes those regions to the Layout plugin. Whereas the current patch has the Renderer asking the DisplayVariant to render the page. So, we need to flip this around!

This way, the standard (and base) renderer would just apply region and block styles. But the IPE renderer would add the extra markup/Javascript necessary to do the in-place editing. And the editor renderer would add the extra buttons/drop-downs/etc to each region/pane that would be used in Page Manager (theoretically, I'm not sure how we'll actually do this in real life, but this is the general idea).

However, I'm not sure if "before the regions go to the Layout" should mean either (a) before we call $layout->build() or (b) before the layout theme function renders the whole thing. I could see an argument for either one...

Also, and this is a super minor thing:

+++ b/src/Plugin/DisplayRenderer/DisplayRendererBase.php
@@ -0,0 +1,67 @@
+  /**
+   * Render the Panels display.
+   *
+   * This is the outermost method in the Panels render pipeline. It calls the
+   * inner methods, which return a content array, which is in turn passed to the
+   * theme function specified in the layout plugin.
+   *
+   * @return string
+   *   Themed & rendered HTML output.
+   */
+  public function render() {
+    return $this->getDisplay()->build();
+  }

Let's call this function build(). There's a sort of convention in D8 that you call creating a render array building, because the actual rendering is done by later.

Feel free to ping me on IRC if you want to discuss this in a higher-bandwidth way!

@brantwynn: Thanks, this is looking really good! All my review from #4 is addressed.

Here's some new review! The first several items are quick fix, nit-picky stuff which should be easy to take care of right away. Then the last few items are deeper architectural things that we might need to hammer on for a bit.

1. +++ b/src/Annotation/DisplayRenderer.php
   @@ -0,0 +1,33 @@
   + * @file
   + * Contains \Drupal\panels\Annotation\DisplayRenderer.php.
   

   Shouldn't have .php

2. +++ b/src/Annotation/DisplayRenderer.php
   @@ -0,0 +1,33 @@
   +  /**
   +   * The human readable title.
   +   *
   +   * @var string
   +   */
   +  public $title = '';
   

   Let's renamed this to 'label' to match layout plugins

3. +++ b/src/Plugin/DisplayRenderer/DisplayRendererBase.php
   @@ -0,0 +1,31 @@
   +  /**
   +   * Render the Panels display.
   +   *
   +   * This is the outermost method in the Panels render pipeline. It calls the
   +   * inner methods, which return a content array, which is in turn passed to the
   +   * theme function specified in the layout plugin.
   +   *
   +   * @return string
   +   *   Themed & rendered HTML output.
   +   */
   

   This should just be {@inheritdoc}

4. +++ b/src/Plugin/DisplayRenderer/DisplayRendererInterface.php
   @@ -0,0 +1,31 @@
   + * @file
   + * Contains \Drupal\panels\Plugin\Renderer\RendererInterface.
   

   Incorrect class name and namespace

5. +++ b/src/Plugin/DisplayRenderer/DisplayRendererInterface.php
   @@ -0,0 +1,31 @@
   +  /**
   +   * Render the Panels display.
   +   *
   +   * This is the outermost method in the Panels render pipeline. It calls the
   +   * inner methods, which return a content array, which is in turn passed to the
   +   * theme function specified in the layout plugin.
   

   This isn't exactly true for Drupal 8, and needs to be updated, however...

6. I just took a look at the Drupal 7 renderer plugins, and I think most of the code from PanelsDisplayVariant::buildRegions() needs to get moved into either the standard renderer or the DisplayRendererBase because in Drupal 7 it's actually the renderer that's responsible for constructing the render array out of the list of configured blocks AND for applying the layout In general, I think we need a pass at making sure we're using renders the same way in D8 as we are in D7.
7. Since we no longer actually "render" anything in the DisplayRenderer, but we just build render arrays, we should actually call this "DisplayBuilder"? That would be similar to "EntityViewBuilder" from core which take an entity and builds a render array.
8. Now that we have the "editor" renderer, we should use it to render the admin form! This doesn't necessarily need to use a UI like in Drupal 7 (yet) but could just put a table like we using currently inside each region. This would then show the block in the actual layout that will be used!

@brantwynn: Awesome, thanks! This is looking really great, and I think we're super close. :-)

At the sprint yesterday, @Crell taught me how to inject services into plugins (it is possisble!) so here is a new version of the patch which does that and performs a little clean-up.

The patch is working great in my manual testing!

A little more review:

1. Let's go ahead rename DisplayRenderer to DisplayBuilder! This also means renaming all the docblocks, $render variables to $builder, and so on to make things consistent.

2. +++ b/src/Plugin/DisplayRenderer/Editor.php
   @@ -0,0 +1,20 @@
   +class Editor extends DisplayRendererBase {
   

   Let's rename this to EditorDisplayBuilder. All the other plugin types repeat the name of the of the plugin in the class name.

3. +++ b/src/Plugin/DisplayRenderer/Standard.php
   @@ -0,0 +1,134 @@
   +class Standard extends DisplayRendererBase implements ContainerFactoryPluginInterface {
   

   And this to StandardDisplayBuilder

4. +++ b/src/Plugin/DisplayVariant/PanelsDisplayVariant.php
   @@ -226,6 +198,20 @@ class PanelsDisplayVariant extends VariantBase implements ContextAwareVariantInt
   +      $manager = \Drupal::service('plugin.manager.panels.display_renderer');
   +      $plugins = $manager->getDefinitions();
   

   Oops! This was something I forgot got to do in the last patch. This should use the injected $this->rendererManager (or, actually, $this->builderManager after the rename) rather than calling \Drupal::service() directly.

5. Can you open a follow-up issue about using the 'editor' builder to build the adminstration form?

Thanks!

1. +++ b/src/Plugin/DisplayRenderer/DisplayRendererBase.php
   @@ -0,0 +1,28 @@
   +  public function build(array $regions, array $context, LayoutInterface $layout = null) {
   

   Oh, and it's Drupal coding standards (I think?) to capitalize NULL

2. +++ b/src/Plugin/DisplayRenderer/DisplayRendererInterface.php
   @@ -0,0 +1,37 @@
   +  public function build(array $regions, array $context, LayoutInterface $layout = null);
   

   Here too!

Hiding super old patch...

Here is a new patch that makes all the changes I requested in #11 and #12. No interdiff because this renames all the files.

And here is a new issue to use the 'editor' display builder in the admin interface: #2553507: Use the 'editor' display builder for admin form

Thanks @tim.plunkett for tracking this down and @brantwynn for the new patch!

We definitely need tests in Panels in general, and I think it totally makes sense to write some tests for the new display builder code.

I'd be reluctant to write tests for the PanelsDisplayVariant at this point, though, since it still contains copy-pasted code from Page Manager which will be eliminated after we finish moving the necessary code to CTools (per #2511554: [meta] Move some parts of Page Manager into CTools) and then do #2511582: Extend BlockDisplayVariant rather than copying code from Page Manager.

Eventually PanelsDisplayVariant will descend from a variant base class which is basically the same as Page Manager's BlockDisplayVariant (except living in CTools) and we can rely on its tests for all that functionality, and then in Panels we only have to test the bits that we overrode. If we wrote tests for it now, we'd probably just throw them all away once the refactor is finished (or end up copy-pasting tests from Page Manage too - but let's just not do that).

However, this mistake was in PanelsDisplayVariant. :-)

Looks good to me! And it worked for me with manual testing. RTBC!