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 after it has been sent to the Drupal theming layer but before it has been rendered 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 from ordinary Drupal render arrays.

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 three 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, and
3. this key's value contains markup that has already passed through the theming layer.

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 the single key '#markup'. For non-collection objects, 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 browser:

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

or

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

or they can prepend/append their own render arrays to $rendered:

  if (isset($rendered[NULL])) {
    array_push($rendered, array('#markup' => '<div>Hello world</div>'));
  }

If you're interested in the reasons why Islandora render arrays differ from node render arrays, see this Jira ticket.