"Render Arrays" or "Renderable Arrays" are the building blocks of a Drupal page, starting with Drupal 7. A render array is an associative array which conforms to the standards and data structures used in Drupal's theme rendering system.
The core structure of Drupal's Render API is the render array, which is a hierarchical associative array containing data to be rendered and properties describing how the data should be rendered.
As a developer you'll use render arrays to describe the content your module controls in order to output it on a page as HTML, or as part of a response in another format like JSON.
Rendering in the Drupal world means turning structured "render" arrays into HTML.
A render array is a classic Drupal structured array that provides data (probably nested) along with hints as to how it should be rendered (properties, like #type). A page array might look like this:
$page = array(
'#show_messages' => TRUE,
'#theme' => 'page',
'#type' => 'page',
'content' => array(
'system_main' => array(...),
'another_block' => array(...),
'#sorted' => TRUE,
),
'sidebar_first' => array(
...
),
'footer' => array(
...
),
...
);
Render array properties
#type -
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.
#cache -
Mark the array as cacheable and determine its expiration time, etc. Once the given render array has been rendered, it will not be rendered again until the cache expires or is invalidated. Uses the Cache API. This property accepts the following subproperties:
'keys'
'contexts'
'tags'
'max-age'
'bin'
#markup-
Specifies that the array provides HTML markup directly. Unless the markup is very simple, such as an explanation in a paragraph tag, it is normally preferable to use #theme or #type instead, so that the theme can customize the markup. Note that the value is passed through \Drupal\Component\Utility\Xss::filterAdmin(), which strips known XSS vectors while allowing a permissive list of HTML tags that are not XSS vectors. (I.e, <script> and <style> are not allowed.)
#plain_text -
Specifies that the array provides text that needs to be escaped. This value takes precedence over #markup if present.
#prefix/#suffix -
A string to be prefixed or suffixed to the element being rendered
#pre_render -
An array of functions which may alter the actual render array before it is rendered. They can rearrange, remove parts, set #printed = TRUE to prevent further rendering, etc.
#post_render -
An array of functions which may operate on the rendered HTML after rendering. A #post_render function receives both the rendered HTML and the render array from which it was rendered, and can use those to change the rendered HTML (it could add to it, etc.). This is in many ways the same as #theme_wrappers except that the theming subsystem is not used.
#theme -
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.
#theme_wrappers -
An array of theme hooks which will get the chance to add to the rendering after children have been rendered and placed into #children. This is typically used to add HTML wrappers around rendered children, and is commonly used when the children are being rendered recursively using their own theming information. It is rare to use it with #theme.
#sorted -
TRUE if the elements of this render array have been sorted by weight. You can set this to FALSE to force Drupal to re-sort the elements in the array. This is useful when adding a new element to a render array in a preprocess hook.