こんにちは。Drupalist見習いの新田です。今回はDrupal8の公式ドキュメントの中の、レンダリングAPI の章の中から、PHPをHTMLに変換するときに必要な情報を渡す役割を持つ「レンダリング配列」の構成や書き方について説明している文章を翻訳しました。ご参考になれば幸いです。

この文章のまとめ

Drupalでいう レンダリング とは「レンダリング配列をHTMLに変換すること」である
レンダリング配列とは「プロパティ」と呼ばれる要素から成る連想配列であり、そのレンダリング配列を適用するものがどのようにレンダリングされるかを定義する（レンダリング配列=[プロパティ、プロパティ、プロパティ・・・]）
レンダリング配列は単一のブロックやエンティティなどに対し適用できる
「要素タイプ（＃type）」と呼ばれるプロパティはそのレンダリング配列内で使える他のプロパティの種類を決める（どんなプロパティが使えるか知りたいときは各要素タイプのページを参照する）
「要素タイプ」以外のプロパティは主にマークアップ、プレーンテキストなどコンテンツの中身を定義するもの、テーマなどレンダリングのルールを定義するもの、プリレンダリングのようにレンダリング配列を操作するもの、ポストレンダリングやテーマ・ラッパーのようにレンダリング後のHTMLを操作するものがある。

(翻訳開始)

レンダリング配列

原文： Render arrays（翻訳時の最終更新日：2018年4月25日）

レンダリング配列（Render Array もしくは Rendable Array）はDrupalのページを構築する部品の一つで、レンダリングAPI用にあらかじめ定められた書き方（スタンダード）やデータ構造を満たす連想配列のことを指します。レンダリングAPIはテーマAPIとも統合されています。

Drupalでは、多くの場合、ページを組み立てるためのデータはレスポンスを生成する最終段階まで配列として保存されます。これによってページを長くしたり、少し変更したり、部分的に全く新しいものに書き換えるというようなことが柔軟に出来るようになります。

レンダリング配列は入れ子状になっており、ツリーを形成します。DOM(Document Object Model)のDrupal版だと考えてください。

注意：レンダリング配列とフォームAPIで使われている配列は共通の要素やプロパティ、構造を持っていますが、フォーム要素のプロパティの多くはフォームAPIでしか意味をなさないため、レンダリングAPIでは使えません。フォームAPIの配列は通常FormBuilderを通じてレンダリング配列に作り変えられますが、それを行なっていないフォームAPIの配列をレンダリングAPIに渡すと予期しない結果を引き起こす可能性があるので注意してください。

「レンダリング」とは何か？

Drupalの世界では、レンダリングとは「レンダリング配列」をHTMLに変換することを指します。詳しくはDrupal8の「レンダリングパイプライン」に関するドキュメンテーションの中の「HTMLメインコンテンツレンダラー」についての項を確認してください。

レンダリング配列とは、「プロパティ」と呼ばれる手がかり（＃typeなど）を用いて、データのレンダリング方法を説明する配列です。例えば「ページ」タイプのレンダリング配列はこのように書かれます。

$page = [
  '#type' => 'page',
  'content' => [
    'system_man' => […],
    'another_block' => […],
    '#sorted' => TRUE,
  ],
  'sidebar_first' => [
    …
  ],
];

なぜレンダリング配列を使うのか

Drupal7以前は、フォームに限ってはhook_form_alter()でHTMLを作り変えることができましたが、他にもモジュールやテーマを使って部分的に作り変えられる必要のあるものが、そうする前にHTMLに変換されてしまうという問題がありました。

Drupal8ではモジュールやテーマを使って任意のブロックのレンダリング配列 (hook_block_view_alter())や任意のエンティティのレンダリング配列(hook_entity_view_alter())など様々なものを作り変えることができます。