構造化された配列のツリーを、HTML の形にレンダリングします。
その際 HTML コードの生成は、配列の各要素に対して再帰的に反復処理されます。
レンダリング配列のキー/値で表される各要素には、「プロパティ」と「子要素」という2つの種類があります。「プロパティ」のキーは「#」で始まり、それらの値は配列がどのようにレンダリングされるかを指定します。キーの頭に「#」の付いていないのは「子要素」です。その値はそれ自身のレンダリング配列となっていて、親要素の配列のレンダリング処理の中でレンダリングされます。レンダリング過程で生成された子要素のマークアップは、通常親要素のマークアップの中に挿入されます。
レンダリング配列の HTML の生成、そして各子要素のマークアップがどのように挿入されるかといったことは、テーマ関数を値にもつ2つのプロパティによってコントロールされます。#theme と #theme_wrappers です。
#theme の値は最初にコールされるテーマ関数です。それが指定されていて子要素がある場合、子要素のレンダリングはそのテーマ関数が担います。子要素を持つことができない要素、たとえばボタンやテキストフィールドなどは、そのテーマ関数が要素自身のレンダリングを行います。#theme の指定がなく子要素がある場合は、子要素は drupal_render_children() によってレンダリング、連結されます。
#theme_wrappers プロパティの値は #theme の値の次にコールされるテーマ関数です。これらはレンダリングされた子要素にさらにマークアップを施す場合（たとえばフィールドセットがその子要素のマークアップをラップする場合など）に使われます。テーマラッパー関数は要素の #children プロパティの値、つまりこの前の処理のテーマ関数によって返されたレンダリング済みの子要素を含む値を返します。
たとえば要素タイプの「フォーム」の場合、デフォルトでは、レンダリングの過程で生成された HTML （フォームの子要素の集合）に、フォームとしての最終的なマークアップを施す #theme_wrappers プロパティが設定されているだけです。特定のフォームをカスタマイズする際には、#theme プロパティに独自のカスタム関数を指定することで、最終的なフォームのマークアップ自体には手を触れずに、フォームの子要素の配置などを完全にコントロールできます。
drupal_render() はパフォーマンス向上のために、オプションで要素のレンダリングされた出力をキャッシュすることができます。drupal_render() のキャッシュ機能を使うには、要素の #cache プロパティに、連想配列で次のような設定を追加します。
この関数は通常 drupal_get_form() やテーマ関数など、別の関数内でコールされます。要素は内部で uasort() を使ってソートそれます。この処理は負荷がかかるので、例えばデータベースクエリからのような、既にソートされた要素を drupal_render() に渡す場合には、$elements['#sorted'] = TRUE のようにセットして、余計なソート処理を避けるようにしてください。
drupal_render() は子要素がレンダリングされると、それぞれに '#printed' プロパティを付与しフラグを立てます。これによって与えられた配列の個々の要素を独立してレンダリング出来るようになり、その後の drupal_render() のコール（例えばより大きな配列の一部としてコールされる場合）によって何度もレンダリングされるのを防ぎます。drupal_render() は同じ配列（レンダリング済みの配列）が渡されると、単に NULL を返します。
$elements レンダリング対象の構造化された配列データ。
レンダリングされた HTML。
includes/common.inc, line 5611
