Since it is important in D8 for module developers to create render arrays (controller functions build and return either a render array or a Symfony Response object), we should document clearly how to create a render array and what are the basic elements it should specify.
I've been looking at the following but still have some questions.
- Render API Overview
- function Renderer::render
- Render API
core/lib/Drupal/Core/Render/BareHtmlPageRenderer.php
core/lib/Drupal/Core/Render/MainContent/HtmlRenderer.php
Render API mentions a few things:
Render arrays (at each level in the hierarchy) will usually have one of the following three properties defined:
- #type type of element: 'page', 'form', 'table', etc.
- #theme name of theme; by existing indicates that render array contains data to be themed by a particular theme hook
- #markup HTML markup
Questions:
1) Is it required to have #type
specified?
2) Is it required to have one of #theme
or #markup
in the render array? Are there other properties that would be alternatives to these two?
3) Do any of #type
, #theme
, #markup
conflict with each other? It would appear that #theme
and #markup
do.
4) It doesn't sound useful for anything, but could a render array be empty? e.g. $render_array = array();
5) Is there a list of all possible values for #type
specified somewhere?
Renderable arrays have two kinds of key/value pairs: properties and children:
- Properties have keys starting with '#' and their values influence how the array will be rendered.
- Children are all elements whose keys do not start with a '#'. Their values should be renderable arrays themselves.
6) Is this accurate? (Double-checking because, if true, there technically wouldn't be a reason to use '#'; perhaps it's for historical reasons?)
7) Are there other properties that are highly-recommended to be added to a basic render array?
for ex., it appears in Cacheability of render arrays that #cache
is.
8) Does Drupal add default properties or children to a render array? Is it simple to document what these are, or does it vary a lot depending on the context? Are there any properties/children that are added to every render array?