Render arrays in Islandora

Two hooks provided by Islandora, hook_islandora_view_object_alter() and hook_cmodel_pid_islandora_view_object_alter(), let developers modify data before it is sent to the Drupal theming layer for rendering to the browser. The data is available in the second parameter to each of those hooks, $rendered, which contains a Drupal render array. Developers should be aware that this render array differs slightly from the render array used for Drupal nodes.

Ordinary Drupal render arrays are flat associative arrays whose keys contain the renderable data and some information about the render array itself:

Array
(
    [#show_messages] => 1
    [#theme] => page
    [#theme_wrappers] => Array
        (
            [0] => html
        )
    [#type] => page
    [content] => Array
        (
            [system_main] => Array
                (
                    [nodes] => Array
                        (
                            [1] => Array
[...]

Islandora render arrays differ in two ways: 1) they contain an intermediate array between the top level of the render array and the data representing the Islandora object, and 2) they only contain a single key, #markup. One further difference distinguishes between collection objects and non-collection objects.

For example, the render array for a collection object has the following structure:

Array
(
    [Collection View] => Array
        (
            [#markup] =>
<div class="islandora-basic-collection-wrapper">
    <div class="islandora-basic-collection clearfix">
    <span class="islandora-basic-collection-display-switch">
      <ul class="links inline">
                  <li>
            <a  href="/islandora/object/islandora%3Asp_basic_image_collection?display=grid" class="islandora-view-grid active">Grid view</a>
          </li>
                  <li>
            <a  href="/islandora/object/islandora%3Asp_basic_image_collection?display=list" class="islandora-view-list">List view</a>
          </li>
              </ul>
    </span>
[...]

Notice the intermediate key 'Collection View', which contains '#markup'. For a non-collection object, this intermediate array has a NULL key:

Array
(
    [] => Array
        (
            [#markup] =>
<div class="islandora-basic-image-object islandora" vocab="http://schema.org/" prefix="dcterms: http://purl.org/dc/terms/" typeof="ImageObject">
  <div class="islandora-basic-image-content-wrapper clearfix">
          <div class="islandora-basic-image-content">
        <a href="http://localhost:8181/islandora/object/islandora%3A226/datastream/OBJ/view"><img typeof="foaf:Image" src="/islandora/object/islandora%3A226/datastream/MEDIUM_SIZE/view" alt="" title="Test 1" /></a>      </div>
      </div>
  <div class="islandora-basic-image-metadata">
    <div class="islandora-metadata-sidebar">
  </div>
          <div>
[...]

Within implementations of hook_islandora_view_object_alter() and hook_cmodel_pid_islandora_view_object_alter(), developers can access and modify the markup in the render array before it gets sent to the theming layer:

  if (isset($rendered[NULL])) {
    // Do something with the content of $rendered[NUL]['#markup']
  }

or

  if (isset($rendered['Collection View'])) {
    // Do something with the content of $rendered['Collection View']['#markup']
  }

or they can append their own render arrays to the one provided within $rendered:

  if (isset($rendered[NULL])) {
    // Do something with the content of $rendered[NUL]['#markup']
    array_push($rendered, array('#markup' => '<div>Hello world</div>'));
  }