making correct return array of ControllerBase

Question

I am new to Drupal 8 and it is hard to comprehend the documentation. I am required to make a custom module. I came across examples in creating custom modules, but I am having difficulty in making the correct return type. For example, consider the code snippet take from doc:

<?php
/**
 * @file
 * Contains \Drupal\hello_world\Controller\HelloController.
 */

namespace Drupal\hello_world\Controller;

use Drupal\Core\Controller\ControllerBase;

class HelloController extends ControllerBase {
  public function content() {
    return array(
        '#type' => 'markup',
        '#markup' => $this->t('Hello, World!'),
    );
  }
}

In this example, the controller is called when some page (defined in route) is visited. In this case an array is returned with #type and #markup, whose definition I cannot find anywhere. Similary consider another example:

<?php
namespace Drupal\acme\Controller;
use Drupal\Core\Controller\ControllerBase;
class DefaultController extends ControllerBase {
  public function hello($name) {
    // the {name} in the route gets captured as $name variable
    // in the function called
    return [
      '#theme' => 'hello_page',
      '#name' => $name,
      '#attached' => [
        'library' => [
          'acme/acme-styles', //include our custom library for this response
        ]
      ]
    ];
  }
}

In this case, the return type is #theme, #name and #attached. These two code clearly shows different return type. As a beginner, I am having difficulty in understanding what to return from function as I cannot see those definitions in the documentation of ControllerBase class.

Where in the documentation are these tags defined and how do I use them in different scenarios? Thanks.

Answer 1

The return type of a Controller can be either a Response or a render array.

A render array is an array that you see in your code, and this is generally the best thing to return for a visible page as it provides the theme layer with opportunity to render into a template.

Render array types (#type) are defined in the Render Arrays docs page. See also the API docs for the RenderElement plugin I linked below.

The element type. If this array is an element, this will cause the default element properties to be loaded, so in many ways this is shorthand for a set of predefined properties which will have been arranged through a RenderElement plugin.

However the render array could also be defined to use a theme/template directly with (#theme), which is defined as

A single theme function/template which will take full responsibility for rendering this array element, including its children. It has predetermined knowledge of the structure of the element.

So the render array return for a Controller will depend on how you wish to structure the content that is displayed in the main content area.