hook_theme

モジュール(もしくはテーマ)のテーマの実装をレジストリに登録します。

このフックの実装は2つの目的のために使用されます。ひとつはそのレンダリング配列がどのように HTML としてレンダリングされるかを特定すること(通常テーマ関数の指定はレンダリング配列の #theme プロパティを使います)、もうひとつは theme() をコールして生成された HTML を返すことです。

以下に示すパラメータはすべてオプションです。

パラメータ

array $existing オーバーライドの目的で使用される既存の実装の配列です。主にテーマが自身の優先度の高いテーマ実装を適切に登録するときなどに、既存のテーマ実装を調べ、引数などのデータを抽出するのに有用です。

$type Whether a theme, module, etc. is being processed. This is primarily useful so that themes tell if they are the actual theme being called or a parent theme. May be one of:

  • 'module': A module is being checked for theme implementations.
  • 'base_theme_engine': A theme engine is being checked for a theme that is a parent of the actual theme being used.
  • 'theme_engine': A theme engine is being checked for the actual theme being used.
  • 'base_theme': A base theme is being checked for theme implementations.
  • 'theme': The actual theme in use is being checked.

$theme The actual name of theme, module, etc. that is being being processed.

$path The directory path of the theme or module, so that it doesn't need to be looked up.

返り値

テーマフックの情報の連想配列を返します。配列のキーはフックの内部名、値はそのフックの情報を含む配列となっています。値の配列はそれぞれ 'variables' か 'render element' のどちらかの要素をもつ必要があります(両方を含めることはできません)。単一の要素、もしくはフォーム、ページ構成の配列といった複数の要素で構成されるツリー、もしくは単一チェックボックス要素などのテーマには 'render element' を使います。いっぽうそのテーマ実装が theme() を通して直接コールされることを意図していて、複数の変数を必要とする場合は、'variables' を使用してください。その場合、テーマをコールする際に指定されていない変数は、ここでデフォルトとして設定したものがテーマ関数(もしくはテンプレートファイル)に渡されます。テーマ情報の配列は次のようなキー/値のペアとなります。

  • variables: (上記を参照) テンプレートに渡す変数を定義する配列です。キーは変数名、値はその変数の、theme() をコールする関数が引数を持たない場合のデフォルト値として使用されます。テンプレートとして実装する場合、配列のキーはそれぞれテンプレートファイルの変数名として使われます(PHP で使用する変数の形になります)。テーマ関数としての実装では、これらの変数は $variables のような1つの変数に格納された形で渡されます。
  • render element: (上記を参照) レンダリングの対象要素、もしくはテーマ関数に渡す要素ツリーの名前です。これはプリプロセス関数やプロセス関数で、レンダリング要素ツリーを保持する変数の名前として使用されます。
  • file: テーマ関数が存在するファイルです。ここでファイルを指定することで、テーマ関数がレンダリングを行う前に、 確実にテーマ関数が(そして必要であればプリプロセス関数も)ロードされるようになります。これによって、テーマ関数を別のファイルに分けてまとめたりといったことが容易になります。
  • path: ファイルのパスを指定する必要がある場合に使用します。デフォルトはモジュール、テーマのパスです。Drupal のルートディレクトリに対する相対パスで記述します。
  • template: これを指定した場合、このテーマ実装はテンプレートとなります。テンプレートファイルの拡張子を除いた名前を指定してください。.tpl.php といった拡張子はデフォルトのレンダリングエンジン( PHPTemplate )によって自動的に追加されます。上記の 'path' を指定した場合、テンプレートファイルはそのパスに置いてください。
  • function: これを指定した場合、このテーマ実装はテーマ関数となり、ここで指定した名前のテーマ関数がコールされます。'template' も 'function' も指定がない場合、デフォルトのテーマ関数の名前が使用されます。たとえば、モジュールが 'node' というテーマフックを登録した場合、'theme_node' がテーマ関数の名前として割り当てられます。chameleon(カメレオン)テーマが node フックを登録した場合は、'chameleon_node' がテーマ関数として割り当てられます。
  • pattern: テーマに動的な名前を持たせたい場合に使用します。規則として '__' で動的な部分を分けることになっています。たとえばフォーラムにそれぞれ個別のテーマを持たせたい場合、パターンは 'forum__' となります。そしてフォーラムをテーマ化する際には、次のようにコールします。:
    <?php
    theme(array('forum__' . $tid, 'forum'), $forum)
    ?>
  • preprocess functions: テーマに渡すデータのプリプロセス(前処理)関数のリストです。自動的に割り当てられるので、通常はこれを使用することはありません。デフォルトでは、モジュールの場合は ' template_preprocess_HOOK' が利用でき、テーマの場合は ' phptemplate_preprocess' と ' phptemplate_preprocess_HOOK'、同様に ' themename_preprocess' や ' themename_preprocess_HOOK' が利用できます。
  • override preprocess functions: 標準のプリプロセス関数を使いたくない場合に TRUE をセットします。変数を完全に制御したい場合に使用することができます。たとえば、テーマが page.tpl.php における変数を確実にトータルコントロールしたいとします。その場合はここで TRUE を指定します。但しテーマでこれを使用する場合、テーマは必要な変数が設定されていることを確認する必要があります。
  • type: (自動で判別)テーマフックがどこで定義されているか。: 'module'、 'theme_engine', そして 'theme'。
  • theme path: (自動で判別)テーマおよびモジュールのパスです。特に気にする必要はありません。

関連トピック

モジュールにコア機能を操作する機会を提供します。

Code

Code modules/system/system.api.php, line 2142

<?php
function hook_theme($existing, $type, $theme, $path) {
  return array(
    'forum_display' => array(
      'variables' => array('forums' => NULL, 'topics' => NULL, 'parents' => NULL, 'tid' => NULL, 'sortby' => NULL, 'forum_per_page' => NULL),
    ), 
    'forum_list' => array(
      'variables' => array('forums' => NULL, 'parents' => NULL, 'tid' => NULL),
    ), 
    'forum_topic_list' => array(
      'variables' => array('tid' => NULL, 'topics' => NULL, 'sortby' => NULL, 'forum_per_page' => NULL),
    ), 
    'forum_icon' => array(
      'variables' => array('new_posts' => NULL, 'num_posts' => 0, 'comment_mode' => 0, 'sticky' => 0),
    ), 
    'status_report' => array(
      'render element' => 'requirements', 
      'file' => 'system.admin.inc',
    ), 
    'system_date_time_settings' => array(
      'render element' => 'form', 
      'file' => 'system.admin.inc',
    ),
  );
}
?>
コア: 
Drupal7