Push usage of drupal_set_page_content() higher: out of blocks and page display variants

D'oh; this was extracted 1:1 from the main patch; will fix both those points — thanks!

As of the above patch, we always call drupal_set_page_content() when block module is enabled. Even if we don't actually render the main content. This means that drupal_prepare_page() will assume we've rendered the main content, and not do this:

  if (!$main_content_display) {
    $page['content']['system_main'] = drupal_set_page_content();
  }

But, most tests (all of the failing ones) DON'T place SystemMainBlock. Hence the main content doesn't become visible.

So the question is: how do we make sure that FullPageVariant always displays the main content? The answer: we check if we rendered a block that does show the main content, and if we didn't, we show it manually. Much like drupal_prepare_page() does.
The only alternative is to let each of those failing tests place SystemMainBlock… which is a huge amount of work.

This moves the responsibility of rendering the main content from the mess/maze/legacy cruft that is drupal_prepare_page() (which relies on crazy hacks with static variables) into clear logic. Other page variants won't have to perform this mess.

Note: this is in fact exactly what the main patch does; see the same files as the ones in this interdiff in the main patch.

#2: fixed in #8!

#3:

• will do in next reroll.
• will add more help in a next reroll.

#4:

I'm not comfortable with that. What if we pass in the block id of the main block via plugin configuration? Something like this (obviously the config also could live in a yaml).

Why aren't you comfortable with that? What's problematic about it? In theory there could be multiple "main content" blocks. Your proposal requires us 1) to know which is the main block, 2) doesn't allow multiple main blocks, 3) doesn't allow an alternative implementation of the main block.

I don't see any benefit to what you propose, and no downside to what's in the current patch? Can you please explain a bit more what you find so problematic? :)

#13: Thanks! But we should test both with and without SystemMainBlock being placed. The main patch provides test coverage for that, so cherry-picking those hunks out of there into this patch also.

Also addressed #3.1, #3.2

#12: But then how is the system supposed to figure out which block is "the main content block"? You'd end up with something similar to this anyway, to figure that out automatically, unless you want to burden the site builder with that effort: (s)he'd have to indicate which block should contain the main content in the UI, which would be a UX regression and very brittle.
This is probably the first time I'm disagreeing with you, so I definitely want to understand your concern and understand how you'd like to see it work!

Is there a reason why we not just simply set the main content of the $page render array? so _block_page_build() can already take it from there? Well, no teal.

We could do that now, I think, but the main patch will remove that: even when block module is disabled, we'll use a page display variant, so that we have a consistent rendering pipeline, that always uses a page display variant. In that patch, that default page display variant (which is used when Block module is not installed) is called SimplePageVariant (name can be changed, of course), and then the page render pipeline looks like this:

      // Select the page display variant to be used to render this main content,
      // default to the built-in "simple page".
      $event = new PageDisplayVariantSelectionEvent('simple_page');
      $this->eventDispatcher->dispatch(SystemEvents::SELECT_PAGE_DISPLAY_VARIANT, $event);

      …

      // Instantiate the page display, and give it the main content.
      $page_display = $this->displayVariantManager->createInstance($variant_id);
      if (!$page_display instanceof PageVariantInterface) {
        throw new \LogicException('Cannot render the main content for this page because the provided display variant does not implement PageVariantInterface.');
      }
      $page_display->setMainContent($main_content);

      // Generate a #type => page render array using the page display variant,
      // the page display will build the content for the various page regions.
      $page = array(
        '#type' => 'page',
      );
      $page += $page_display->build();

When Block module is enabled, it just always overrides it to its own page display variant. If Page Manager or Panels or something else is enabled, then that would be used. When using multiple, it'd be up to the event priority and whatever logic the event subscriber uses to determine which wins.

I hope that made sense.

Any other concerns, or is this RTBC? :)