こんにちは。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())など様々なものを作り変えることができます。

レンダリング配列は「要素タイプ」とどう関係があるのか

モジュールは必ず「要素タイプ」と呼ばれるデフォルトのレンダリング配列を持っており、それを定義することができます。新しい要素タイプを定義するには、ElementInterfaceを継承するRenderElementプラグインを新しく作る必要があります。

レンダリング配列のプロパティ

一つのレンダリング配列には本当にたくさんのプロパティを入れることができます。必要とあればプロパティを追加することもできます。以下で特によく使われるプロパティを説明します。 (デフォルトのレンダリング要素のプロパティは上のリンク先にあるRenderElementAPI ページをご覧ください。)

代表的なプロパティの説明

  • #type(要素タイプ) Drupal8ではここを設定することによりデフォルトの要素プロパティが読み込まれ、RenderElementプラグインを使って行われてきたようなプロパティ設定を省略することができます。

  • #cash(キャッシュ) 配列のキャッシュを有効化し、キャッシュの保存期間を決めることができます。一度配列がレンダリングされると、キャッシュの保存期間が切れるかキャッシュが無効化されるまで再び同じ配列がレンダリングされることはありません。このプロパティはキャッシュAPIを使用します。'keys'、'contexts'、'tags'、'max-age'、'bin'というという副次的プロパティを加えることができます。詳しくはキャッシャビリティについての項をご覧ください。正しくキャッシュを設定することはとても大事です!

  • #markup(マークアップ) 配列にHTMLマークアップを直接出させたい場合に設定します。「<p>タグに入れられた文章」のようにとてもシンプルな内容でない限り、#themeや#typeを使うのが好ましいです。このプロパティは\Drupal\Component\Utility\Xss::filterAdmin()を通して渡され、XSSベクターは剥ぎ取られてXXSベクターでない一部のHTMLのみが採用されることに注意。(例えば<script><style>は使えない)

  • #plain_text(プレーンテキスト) エスケープされる必要のあるテキストを示します。この値は#markupよりも優先されます。

  • #prefix/#suffix(接頭辞・接尾辞) レンダリングされる要素の前と後ろに付け加えたい文字列を定義します。

  • #pre_render(プリレンダリング) 複数の関数をまとめた配列で、レンダリング配列がレンダリングされる前にその配列を変化させたいときに使います。パーツを並べ直したり、取り除いたりすることができます。レンダリングをさせたくないときは #printed = TRUE と書いてください。

  • #post_render(ポスト・レンダリング) すでにレンダリングされたHTMLに対して操作を行うための関数をまとめた配列です。それらの関数はレンダリング結果であるHTMLと元のレンダリング配列を受け取り、HTMLに操作を加えます。テーマ作りの仕組みを使っていないというだけで#theme_wrappersととてもよく似ています。

  • #theme(テーマ) レンダリング配列と子配列の要素を受け取って作り変える単一のテーマ関数/テンプレートです。事前に決められたテーマの要素についての情報を持っています。

  • #theme_wrappers(テーマ・ラッパー) 子テーマがレンダリングされて#childrenに送られた後にレンダリング結果を追加するためのテーマ用フックです。よくレンダリング後に子テーマの周りに付け足したり、子テーマがテーマ情報を使って再帰的にレンダリングされているときに使われます。#themeと同時に使うことは滅多にありません。

  • #sorted(並べ替え) 重さ(weight)に基づいてこのレンダリング配列の要素を並べたい時はTRUEにします。Drupalに強制的に配列を並べ替えさせたい時はFALSEを使います。他のレンダリング配列を加工するフックによってレンダリング配列に新しい要素を追加したい時に便利です。

全ての要素タイプがそのタイプに適する範囲で自分のプロパティを宣言することができるので、まだまだ色々なプロパティが存在します。個々の要素タイプに特有のプロパティはその要素のドキュメントに書かれています。要素タイプのリストはこちらでご覧ください。

(翻訳終わり)


共に働く新しい仲間を
募集しています

スタジオ・ウミは「Drupal」に特化したサービスを提供する Drupal のエキスパートチーム。
フルリモート&フレックス制だから、働く場所を選ばず時間の使い方も自由です。
そんなワークライフバランスの整った環境で、当ブログに書かれているような
様々な技術を共に学びながら、Drupalサイト開発に携わってみたい方を募集しています。
まずはお話だけでも大歓迎!ぜひお気軽にご連絡ください。