More Related Content Similar to Drupalテーマとthemingの基礎 (20) Drupalテーマとthemingの基礎2. 内容
• Drupal テーマの概要
• テーマの管理と設定
• テーマのインストール
• テーマの .info ファイル
• リージョン
• テンプレート変数
• テーマ関数
• suggestion
3. Drupal のレイヤー構造とフロー
1. データ(ノードなど)
– コンテンツの基になるデータ
2. モジュール
– 追加機能を提供するプラグイン
3. ブロックとメニュー
– モジュールの出力コンテンツ
• ページ:独自のURLを伴うもの
– メニュー項目として設定できる
• ブロック:ページ内の区画に出力されるもの
– レイアウト上の区画をリージョンと呼ぶ
4. ユーザーのアクセス許可
– ユーザーにロールを割り当て
– 各ロールに種々の権限を与える
5. テンプレート
– 最終的な出力コンテンツを生成する
– HTML、CSS、PHP 変数
出典(図)https://drupal.org/getting-started/before/overview
4. テーマとテーマ エンジン
• テーマとは?
– サイトの外観を定義する、テンプレート、スタイルシート、スクリプト等を
まとめたソフトウェアパッケージのこと
– Drupal サイトに導入できる種々のテーマが開発・公開されている
• テーマ エンジンとは?
– テンプレートのコードを解釈して動的にコンテンツを生成する処理系
– Drupal 7 の標準テーマ エンジンは PHPTemplate
• PHP で書かれた .tpl.php ファイルをそのままテンプレートとして使用する
– その他のテーマエンジン
• https://drupal.org/project/project_theme_engine
• D8 では標準テーマエンジンが Twig になる
5. テーマの例
• コアに付属するテーマ
– Bartik
• Drupal 7 インストール後の初期デフォルト テーマ
– Garland
• Drupal 5 のコア標準テーマ、Color モジュール対応、fixed/fluid 切替対応
– Seven
• Drupal 7 のデフォルト管理用テーマ
– Stark
• Drupal のデフォルト HTML マークアップをデモする最小構成テーマ
• drupal.org の配布テーマ一覧(contributed themes)
– https://www.drupal.org/project/project_theme
6. Drupal サイトのテーマを管理する
1. デフォルトテーマの設定
2. 管理用テーマの設定
3. テーマのグローバル設定
– ロゴ
– サイト名とスローガン
– ショートカットアイコン(ファビコン)
– ユーザーのアイコン(アバター)
– コメントにおけるユーザー検証の設定
– メインメニュー、セカンダリメニュー
4. カスタム テーマ設定
5. テーマの追加インストール
Drupal 7 サイトにおける
テーマ管理の操作内容と
設定項目を見ていきます。
下記ページからスタート:
admin/appearance
7. 1. デフォルト テーマの設定
• デフォルトテーマの設定
– 有効にするだけでなくデフォルト テーマにすることで通常表示されるテーマを指定する
• デフォルトテーマとは、一般のサイト訪問者に表示されるテーマ(フロントエンドテーマ)のこと
デフォルトテーマが先頭に
この例では Seven も有効になっている。
[デフォルトに設定] リンクをクリックすると
デフォルトテーマに設定される
8. 2. 管理用テーマの設定
• 管理用テーマ
– サイトの管理に関するパス(URL)に適用されるテーマ
• /admin 配下のパスを持つページ
– コンテンツ編集用のページに適用することもできる
– デフォルトテーマの設定ページの一番下にある UI で指定する
デフォルトテーマまたは
インストール済みテーマの
中から選択・指定する
コンテンツ編集ページに
適用することもできる
9. 3. テーマのグローバル設定 (1)
• 全テーマ共通の環境設定
– インストール済みの全テーマに適用されるデフォルト設定を指定できる
• パス: admin/appearance/settings
• 個別のテーマの設定で再定義できる
10. 3. テーマのグローバル設定 (2)
設定項目 説明
ロゴ ロゴは、デフォルトでテーマディレクトリの直下にある logo.png というファイル
が使われる。別のファイルをアップロードしたり、別のパスを指定することもでき
る。テーマ設定で有効にすると、変数 $logo にロゴのパスを含むコンテンツ
が設定され、テンプレートファイル page.tpl.php で利用できるようになる。
サイト名
スローガン
admin/conifg/system/site-information の UI から指定でき、テー
マ設定で有効にすると、それぞれ変数 $site_name、$site_slogan
としてテンプレートファイル page.tpl.php から利用できるようになる。
ショートカット アイコン デフォルトは misc/favicon.ico のファイルが使用される。ロゴと同様、別
のファイルをアップロードしたり別のパスを指定することもできる。
投稿でのユーザーアバター
コメントでのユーザーアバ
ター
それぞれ、テンプレートファイル page.tpl.php の $user_picture 変
数、テンプレートファイル comment.tpl.php ファイルの $picture 変
数の有効/無効を設定する。有効にするとノードやコメントにアバターが表示
される。
コメントの承認状況 ログインによって検証されたアカウントを使用していない場合、ユーザー名の
横に "(not verified)" と表示するオプション。この表示文字列は関数
template_process_username() で $variables['extra'] と
して定義され、theme_username()で出力される。
11. 3. テーマのグローバル設定 (3)
設定項目 説明
メインメニュー
セカンダリー メニュー
このチェックボックスをオンにすると、テンプレートファイル page.tpl.php で
使用する変数 $main_menu と $secondary_menu にそれぞれ
のメニューのリンクを格納した配列がセットされる。どの定義済みメニューをメ
インとセカンダリに使用するのかは、admin/structure/menu/settings
の設定 UI から指定できる。デフォルトでは次のメニューが設定されている。
メインメニュー
admin/structure/menu/manage/main-menu
セカンダリメニュー
admin/structure/menu/manage/user-menu
いずれも、テンプレートファイル page.tpl.php 内で theme_links()
関数を使用して出力される単純な単一階層メニューだが、高度なナビゲー
ションのデザインが難しいため、これらのメニューを使用する代わりに、メニュー
用のリージョンを用意してブロックとしてメニューを出力するテーマも多い。
12. 4. カスタム テーマ設定
• テーマやモジュールによって提供されるテーマ設定
– 特定のテーマやモジュールによって提供されるテーマ設定もある
• 例)Garland テーマの [コンテンツの幅] 設定
– 固定幅か可変幅(フルード)かを指定する
13. 5. テーマの追加インストール
• テーマのインストール場所:
– themes フォルダ
• コアのテーマのインストール場所
• サイト固有のカスタムテーマはここにインストールしないこと
– インストールするとコアの更新で削除されたり上書きされる恐れがある
– sites/all/themes フォルダ
• Drupal のインストール環境すべてで共用されるテーマはここにインストールする
• 管理画面からテーマをダウンロードした場合もここにインストールされる
– sites/<サイト名>/themes フォルダ
• 特定のサイト固有のテーマはここにインストールする
– <サイト名> にはサイトのドメインが入る
• テーマインストーラの利用
– UI にテーマの tar.gz ファイルの URL を指定して実行する
• http://d7base.local/admin/appearance/install
• sites/all/themes の下にインストールされる
14. .info ファイルについて
• .info ファイル
– テーマのメタデータを記載するファイル
• 例)テーマ名、サポートするDrupalのバージョンなど
– .info ファイルの作成がテーマ作成の最初のステップ
– ファイル名(.info を除いた部分)がテーマの内部名になる
• Drupal がテーマの情報をデータベースに保存する際に内部名が使用される
• ダッシュ記号その他の特殊文字は使用できない
• アンダースコアは使用できるがなるべく避ける
– 内部名はテーマ関数のオーバーライドするときのプリフィクスになる。
アンダースコアは関数オーバーライドの区切り文字なので、
内部名にアンダースコアがあるとプリフィクスの範囲がわかりづらくなる。
– 例)theme_menu_link() をオーバーライドする場合:
» アンダースコアなし themename_menu_link()
» アンダースコアあり theme_name_menu_link()
○
×
15. .info ファイルのプロパティ (1)
プロパティ 説明
core(必須) このテーマをサポートする Drupal コアのバージョン
name(必須) 人間が読むためのテーマ名(内部名と違っていてもよい)
base theme このテーマがサブテーマの場合に使用するベーステーマの内部名を指定する。
description テーマの基本機能や用途を記述する。ここに記述した内容が
admin/appearance ページに表示される。
engine 使用するテーマエンジンを指定する。デフォルトのPHPTemplate以外のエ
ンジンを使用する場合にのみ指定する。
features Drupal のデフォルトテーマ設定を再定義する場合に指定する。
php テーマに特定の PHP バージョンでのみ動作するコードが含まれる場合に、
そのバージョンを指定することができる。
regions ブロックの出力先となるページ内のレイアウト要素を定義する。角カッコ内に
にシステム名を指定し、右辺の値として人間が読むための名前を指定する。
settings テーマのカスタム設定を実装するために予約されているプロパティ。
カスタムテーマ設定については下記を参照:
https://www.drupal.org/node/177868
16. .info ファイルのプロパティ (2)
• .info ファイルの書き方の詳細は下記を参照:
– https://drupal.org/node/171205
プロパティ 説明
screenshot テーマ設定ページに表示されるスクリーンショット画像を指定する。デフォルト
でテーマディレクトリにある screenshot.png ファイルが表示されるので通
常は指定する必要なし。画像の推奨サイズは 294 x 219 ピクセル。
stylesheets 全ページで使用するスタイルシート(CSS)ファイルを指定する。
scripts 全ページで読み込むスクリプトファイルを指定する。
version このテーマのバージョンを指定する。ただし、バージョンは drupal.org のパッ
ケージ用スクリプトで管理されるため、個別に指定することは推奨されない。
17. 実習:テーマを作ってみよう
• ただ動くだけで中身は空の hoge テーマを作る:
1. sites/all/themes フォルダに hoge フォルダを作る
2. hoge フォルダの下に hoge.info ファイルを作る。
• NetBeans の Drupal プラグインを使用している場合は、
[新規作成] - [PHP] - [Drupal Theme] を選択することで
自動的にフォルダとファイルのひな形が作成される。
3. hoge.info を次のように編集して保存する:
4. screenshot.png ファイルを作成して hoge フォルダに保存する。
5. admin/appearance ページを表示すると hoge テーマが見える
• デフォルト テーマに設定できる
name = hogeテーマ
description = 実習で作成したテーマ1
core = 7.x
18. グローバル設定の再定義
• features プロパティでグローバル設定を再定義できる
– 各テーマの .info ファイルでグローバル設定の既定値を再定義できる
• 1つも記載しなければ、すべてのグローバル設定が既定値のままとなる
• 1つでも記載すると、すべての要素を .info で指定する必要がある
– 記載しない(またはコメントアウト)設定項目は表示されなくなる
features[] = logo
features[] = name
features[] = slogan
features[] = favicon
features[] = main_menu
features[] = secondary_menu
features[] = node_user_picture
features[] = comment_user_picture
features[] = comment_user_verification
デフォルトのテーマ設定を再定義する .info の features エントリ
19. 実習:グローバル設定を再定義してみよう
• hoge テーマのグローバル設定を再定義する:
1. hoge.info ファイルに前スライドの各 features エントリを追加する。
2. テーマレジストリのキャッシュをクリアする:
• インストール時の設定がキャッシュされるため、
変更した場合はキャッシュをクリアしないと
反映されないので要注意
3. hoge テーマのテーマ設定 UI を確認する。
• すべての設定項目が表示されている
4. 追加した features エントリのいずれかをコメントアウトする
• 行頭にセミコロン(;)を挿入するとコメントアウトできる
5. 再度テーマレジストリのキャッシュをクリアする
6. hoge テーマのテーマ設定 UI を確認する。
• コメントアウトした設定が表示されなくなる コメントアウトした
プロパティの設定項目が
表示されなくなる
21. Drupal 7 テーマを構成するファイル (2)
• .info ファイル(必須)
– テーマのメタデータ、スタイルシート、JSファイル、リージョン等を定義
– .info ファイルの名前がテーマの内部名を定義する
• テンプレート(.tpl.php)ファイル
– 動的に生成される特定部分のマークアップ コンテンツを定義する
• HTML、RSS (XML)、・・・
– 既定のファイルを独自のバージョンで置き換えることができる
• 既定のファイルと同名ファイルをテーマのディレクトリ配下に配置するとそちらが優先して使用される
• suggestion:テンプレートファイルの適用対象を絞り込む命名規則
• template.php
– ロジックやデータ処理を行うコードを記述するファイル
• 出力前の前処理、テーマ関数(後述)のオーバーライド 等
• その他
– ロゴ、スクリーンショット
– theme-settings.php
22. リージョンについて
• リージョンとは?
– コンテンツの出力先となる、ページ内の区画領域のこと
• テンプレート内の該当する位置にコンテンツ出力コードを埋め込んで実装する
– HTML マークアップの高レベルの構造定義に用いられる
• リージョンに出力されるひとまとまりのコンテンツをブロックと呼ぶ
– コアの UI を利用してリージョンにブロックを割り当てる
• パス: admin/structure/block
• 出力先のリージョンを変更することで
ブロックの表示位置を自由に変更できる
– テーマとの関係
• リージョンの配置、表示、スタイル等は
テーマによって定義される
23. コアのデフォルト リージョン (1)
• Drupal コアが定義するリージョン
– プログラムから利用できる9つのデフォルト リージョンが用意されている
• .info ファイルの書式で記述すると次のようになる:
• regions[] の記述がなければ、このデフォルト リージョンが適用される
• regions[] の記述を(1つでも)すると .info に従ってリージョンが設定される
regions[page_top] = Page Top
regions[header] = Header
regions[highlighted] = Highlighted
regions[help] = Help
regions[content] = Content
regions[sidebar_first] = Sidebar First
regions[sidebar_second] = Sidebar Second
regions[footer] = Footer
regions[page_bottom] = Page Bottom
24. コアのデフォルト リージョン (2)
• コアのデフォルト リージョンの想定レイアウト
page_top
page_bottom
footer
header
sidebar_secondsidebar_first
highlighted
content
help
25. コアのデフォルト リージョン (3)
• 主要リージョンの解説
– page_top、page_bottom
• サイトが正常に動作するために必要な必須リージョン
• ブロック設定の UI には表示されない非表示リージョン(後述)
– highlighted
• 旧バージョンの Site Mission に対応する
– Site Mission とはサイトの目的や短い説明文を出力するもの
– 従来の設計では、フロントページに限定される等の制約が多かったため、
Drupal 7 から専用のリージョンに出力する設計に変更された。
– help
• エラーやステータスメッセージ用のリージョン
– "システム ヘルプ" ブロックとして出力され、その出力先として用意されている。
– content
• "メインページ コンテンツ" ブロックを出力するためのリージョン
– このブロックは特別扱いされ、ブロックの管理 UI で無効にしても必ず表示される
26. コアのデフォルト リージョン (4)
• 非表示リージョンについて
– モジュールやテーマが動的にマークアップを追加するプレースホルダ
– ブロック管理 UI に表示されない
– .info ファイルで次のように宣言して指定できる
• regions_hidden[] = <リージョン名>
• コアの非表示リージョン
– page_top
• Tools モジュール(コア)が管理用のツールバーを表示する領域として利用
– page_bottom
• モジュールがページの末尾にマークアップを追加するための領域として利用
– 例)Google Analytics モジュールのアクセス追跡用スクリプトの埋め込み先として
• 旧 Drupal6 の $closure 変数に代わるもの
27. (参考)html.tpl.php の内容
<!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xml:lang="<?php print $language->language; ?>" version="XHTML+RDFa 1.0"
dir="<?php print $language->dir; ?>"<?php print $rdf_namespaces; ?>>
<head profile="<?php print $grddl_profile; ?>">
<?php print $head; ?>
<title><?php print $head_title; ?></title>
<?php print $styles; ?>
<?php print $scripts; ?>
</head>
<body class="<?php print $classes; ?>" <?php print $attributes;?>>
<div id="skip-link">
<a href="#main-content" class="element-invisible element-focusable"><?php print
t('Skip to main content'); ?></a>
</div>
<?php print $page_top; ?>
<?php print $page; ?>
<?php print $page_bottom; ?>
</body>
</html>
出力されるコンテンツのマークアップ全体構造を定義するテンプレート。
page_top、page_bottom の各非表示リージョンは、hook_system_info_alter() を
使用して宣言されている。詳細については下記を参照:
http://api.drupal.org/api/function/system_system_info_alter/7
28. 実習:hoge テーマのリージョンを確認しよう
• hoge テーマのリージョンを確認する:
– hoge テーマをデフォルト テーマに設定する
– admin/structure/block でリージョン名を確認
– admin/structure/block/demo/hoge で各レイアウトを確認
• 最初に作成した hoge テーマの .info にはリージョンの定義がなかったので、
この場合は Drupal コアのデフォルト リージョンが用意されていることがわかる。
• hoge テーマのリージョンをカスタマイズする:
– hoge.info ファイルに前のスライドの regions[] の一覧を転記する
– テーマレジストリのキャッシュをクリア
– admin/structure/block でリージョン名を確認
– hoge.info で一部のリージョンをコメントアウト(行頭に;を配置)する
– 再度テーマレジストリのキャッシュをクリア
– admin/structure/block でリージョン名を確認
.info に regions[] を記述してデフォルトリージョンを再定義できる
29. リージョンに関するその他の事項
• モジュール固有のリージョン
– ブロック管理 UI で制御できないモジュール固有のリージョンも存在する
• 例)Dashboard モジュールの Dashborad Main、Dashborad Sidebar
– これらのリージョンは Dashboard モジュールが作成したもの
– hook_system_info_alter() 関数を使用して定義される
• ブロックを出力する2つの方法
– リージョンを使用する
• ページ内の出力位置を変える可能性があるコンテンツにはリージョンを利用
– テンプレート内に変数出力コードをハードコードする
• 特定の出力位置を前提とするコンテンツは固定位置に埋め込む方法もある
• レイアウトについての留意事項
– 特定リージョンが表示されるかどうかでレイアウトが崩れないようにする
• この種の問題は実績のあるベーステーマの利用で解決できる
31. リージョンへのコンテンツ割り当て
• ブロック リージョン
– テンプレート内に設けられる、コンテンツの出力先となる区画
• .info における定義構文
– 内部名:処理系が使用する識別名
– 表示名:ブロックの管理 UI に表示される表示名(人間のための識別名)
• この定義がない場合はデフォルトのリージョンが使用される
– 先の実習で確認したとおりです
• リージョンのコンテンツを出力するコードをテンプレートファイルに埋め込む
– リージョンを出力するコードは
– page_top、page_bottom の各リージョンは html.tpl.php テンプレートファイルに
– それ以外のデフォルト/カスタム リージョンは page.tpl.php テンプレートファイルに
regions[<内部名>] = <表示名>
32. 実習:新しいリージョンを追加してみよう
• .info ファイルに次のカスタムリージョンを追加する:
• modules/system フォルダから page.tpl.php を探して、
hoge テーマのフォルダにコピーする
• banners リージョンを埋め込む場所に次のコードを記述する:
– content リージョンのすぐ下など
• テーマキャッシュをクリアしてブロック管理のUIに移動すると
Banners リージョンが追加されている。
– 既存ブロックを割り当てるとテンプレート内の該当位置にコンテンツが表示される
regions[banners] = Banners
<div class="banners">
<?php print render($page['banners']); ?>
</div>
33. 実習:メニューをリージョンに配置してみよう
• .info ファイルに次のカスタムリージョンを追加する:
• page.tpl.php から次の部分を削除して、
下記コードで置き換える:
• ブロック管理 UI から "ナビゲーション" リージョンに "メインメニュー" ブロックを割り当てる
– 日本語環境では表示名 Navigation の日本語訳 "ナビゲーション" が表示される
regions[navigation] = Navigation
<?php if ($main_menu || $secondary_menu): ?>
<div id="navigation"><div class="section">
<?php print theme('links__system_main_menu', array('links' => $main_menu,
'attributes' => array('id' => 'main-menu', 'class' => array('links', 'inline',
'clearfix')), 'heading' => t('Main menu'))); ?>
<?php print theme('links__system_secondary_menu', array('links' =>
$secondary_menu, 'attributes' => array('id' => 'secondary-menu', 'class' =>
array('links', 'inline', 'clearfix')), 'heading' => t('Secondary menu'))); ?>
</div></div> <!-- /.section, /#navigation -->
<?php endif; ?>
<?php print render($page['navigation']); ?>
34. Drupal コアのデフォルト テンプレート
• Core がデフォルトの .tpl.php ファイルを提供している
– ファイルの一覧はこちらから ⇒ https://drupal.org/node/190815
• 主要なもの
– block.tpl.php(ブロック)
– commnt.tpl.php(コメント)
– field.tplphp(フィールド)
– node.tpl.php(ノード)
– システム モジュール用のテンプレート
• page.tpl.php(ページ)
• maintenance-page.tpl.php(メンテナンスページ)
• region.tpl.php(リージョン)
• html.tpl.php(全体構造)
テーマ ディレクトリに同名ファイルを用意することで優先して使用される
(デフォルトのテンプレートをテーマ側でオーバーライドできる)
各テンプレートごとに、使用できる
テンプレート変数が用意されている
35. コアの共通テンプレート
名前 コア オリジナル版の場所 使用目的
html.tpl.php modules/system HTML ドキュメントの全体構造を出力する。
$scripts、$styles を含む head 要素の内容や、
$page_top、$page_bottom の各リージョンが
出力される body 要素もこのファイルで出力される。
DOCTYPE を変更する必要がない限り、通常この
ファイルをオーバーライドすることはない。
page.tpl.php modules/system $logo、$site_name、$tabs、$main_menu
などページレベルのリージョンおよびその他の変数を
出力する。このファイルを操作することで、サイトのレ
イアウトを完全に制御できる。ほとんどのテーマはこ
のテンプレートの独自バージョンを提供する。
region.tpl.php modules/system リージョンのHTMLマークアップを出力する。
block.tpl.php modules/block ブロックのHTMLマークアップを出力する。
node.tpl.php modules/node ノードのHTMLマークアップを出力する。
comment.tpl.php modules/commet コメントのHTMLマークアップを出力する。
field.tpl.php modules/field/theme フィールドのマークアップを出力する。
(テーマでオーバーライドする場合にのみ使用する)
36. グローバル テンプレート変数
• すべてのテンプレートで使用できる変数
変数 説明
$is_admin 現在のログインユーザーが管理者ならtrue、それ以外はfalse。
$logged_in 現在のユーザーがログインしている場合はtrue、匿名ならfalse。
$user->uid が 0 なら匿名ユーザと判断する。
$is_front drupal_is_front_page()関数を使用して現在のページがフロントページ(サイトの
トップページ)かどうかを判定する。フロントページならtrue、それ以外はfalse。
$directory テンプレートが格納されているディレクトリ。
$user 現在ログインしているユーザーのアカウント情報を格納したオブジェクト。
テンプレートに global $users; というコードを追加すると利用可能となる。セキュリティ
上危険なものが含まれる可能性があるのでプロパティを直接表示せず、theme() 関
数を利用すること。
$language 現在使用されている言語に関する情報を格納したオブジェクト。
$language->dir はテキストの向き、$language->language は言語コード
(例:英語ならen)など。テンプレートに global $language; というコードを追加す
ると利用可能となる。
$theme_hook_suggestions テンプレートファイルの命名規則やテーマ関数に使用できるテーマフックを格納した配列。
$title_prefix
$title_suffix
テンプレートのタイトルの前後、タイトルが存在しない場合にテンプレートファイルの先頭
や末尾に出力される要素を格納した表示用配列。
37. HTML 属性
• Drupal7 から属性は配列に格納されるようになった
– これにより、コンテンツ生成の前処理で属性値の参照/操作が可能となる
変数 説明
$attributes 別に扱われる class 属性を除き、モジュール(RDFなど)によって提
供されるHTML属性を格納している。$attribute(プリプロセスでは
$attributes_arrayとして利用可能)は、<body>や他のテンプ
レートにおける最上位の<div>など、トップレベルのHTML要素用に
予約されている。
$classes テンプレートのHTMLのclass属性が格納されている。通常、
<body>や他のテンプレートにおける最上位の<div>など、トップレベ
ルのHTML要素用に予約されている。
$title_attributes ノードやブロックのタイトルなど、テンプレートファイルのトップレベルの見出
しの class 属性が格納されている。ノードのティーザやブロックのコンテ
ンツの場合、見出しは通常<h2>となる。
$content_attributes コンテンツのラッパー<div>やテンプレートの投稿本文のclass属性が
格納されている。これらの変数の使用例はnode.tpl.phpファイルが参
考になる。
38. テンプレートのドキュメンテーション
• 変数ドキュメントとしてのテンプレートファイル
– コアテンプレートの冒頭部分には利用可能な変数の詳しいドキュメント
がコメントとして記載されている。
• 例:modules/block/block.tpl.php の変数ドキュメント
– コメントの一番上にある @file ブロックはファイルの概要を示す
– その下に利用可能な変数の長いリストが続く
– 最後に適用可能な前処理および処理の関数が記載されている
<?php
/**
* @file
* Default theme implementation to display a block.
*
* Available variables:
* - $block->subject: Block title.
* - $content: Block content.
* - $block->module: Module that generated the block.
* - $block->delta: An ID for the block, unique within each module.
* - $block->region: The block region embedding the current block.
・・・
39. テンプレートの例:block.tpl.php (1)
・・・
* - $classes: String of classes that can be used to style contextually through
* CSS. It can be manipulated through the variable $classes_array from
* preprocess functions. The default values can be one or more of the
* following:
* - block: The current template type, i.e., "theming hook".
* - block-[module]: The module generating the block. For example, the user
* module is responsible for handling the default user navigation block. In
* that case the class would be 'block-user'.
* - $title_prefix (array): An array containing additional output populated by
* modules, intended to be displayed in front of the main title tag that
* appears in the template.
* - $title_suffix (array): An array containing additional output populated by
* modules, intended to be displayed after the main title tag that appears in
* the template.
*
* Helper variables:
* - $classes_array: Array of html class attribute values. It is flattened
* into a string within the variable $classes.
* - $block_zebra: Outputs 'odd' and 'even' dependent on each block region.
* - $zebra: Same output as $block_zebra but independent of any block region.
* - $block_id: Counter dependent on each block region.
* - $id: Same output as $block_id but independent of any block region.
* - $is_front: Flags true when presented in the front page.
* - $logged_in: Flags true when the current user is a logged-in member.
* - $is_admin: Flags true when the current user is an administrator.
* - $block_html_id: A valid HTML ID and guaranteed unique.
・・・
40. テンプレートの例:block.tpl.php (2)
・・・
*
* @see template_preprocess()
* @see template_preprocess_block()
* @see template_process()
*
* @ingroup themeable
*/
?>
<div id="<?php print $block_html_id; ?>" class="<?php print $classes; ?>"<?php print
$attributes; ?>>
<?php print render($title_prefix); ?>
<?php if ($block->subject): ?>
<h2<?php print $title_attributes; ?>><?php print $block->subject ?></h2>
<?php endif;?>
<?php print render($title_suffix); ?>
<div class="content"<?php print $content_attributes; ?>>
<?php print $content ?>
</div>
</div>
41. テーマ関数について
• テーマ関数とは?
– モジュールが提供する、オーバーライド可能なコンテンツ生成用の関数
• モジュール内の各部から必要に応じて呼び出されるマークアップ生成処理
– 目的:
• テーマ側でカスタマイズできる HTML マークアップ生成処理を実装する
• 本質的にはテンプレートファイルと同じ目的を持つ
– テンプレートとテーマ関数、使い分けの判断基準は?
• 再利用の頻度
• カスタマイズするのはどんな人?(PHPコードをいじれる人かそうでないか)
• パフォーマンス
– テーマ関数として実装した方がテンプレートより若干速度は向上する
• まとまったサブコンテンツか、コンテンツの一部として埋め込みまれる断片か
– 前者はテンプレート、後者はテーマ関数を使用して生成する場合が多い
43. 実習:テーマ関数をオーバーライドしてみよう
• デフォルトの theme 関数をテーマ側でオーバーライドしてみよう
– 題材:theme_menu_link()
• https://api.drupal.org/api/drupal/includes%21menu.inc/function/theme_menu_link/7
• ナビゲーション等のメニューの出力に使われている
• 実習手順
1. オリジナルのテーマ関数をコピーしてテーマの template.php に貼り付ける
• 具体的には、includes/menu.inc の 1625 行目から始まる関数の定義を
hoge テーマの template.php に貼り付ける。
2. 貼り付けた関数の名前の "theme_" の部分をテーマ名に書き換える
• 具体的には、theme_menu_link を hoge_menu_link に書き換える
3. テーマレジストリのキャッシュをクリアする
これで、theme_menu_link() の代わりに
hoge_menu_link() が呼び出されるようになる。
生成するタグに変更を加えて結果を確かめてみよう。
44. hook_theme() について
• テーマ関数もテンプレートも hook_theme() で定義される
– 例えば、テンプレートファイル node.tpl.php や テーマ関数 theme_node() とは、
どちらも node モジュールの node_theme() で定義される。
• テンプレートとテーマ関数を両方同時に使うことはできない。
– どちらを使うかは、hook_theme() のオーバーライド関数が返却する
連想配列の設定で決まる。詳しくは下記資料を参照:
• https://api.drupal.org/api/drupal/modules%21system%21system.api.php/func
tion/hook_theme/7
– 例:コアの node モジュール(modules/node/node.module)の場合:
• node_theme() 関数を見ると、テーマ関数 node の連想配列に
'template' => 'node' というエントリがある。
これは node_theme ではテンプレートを使用すること、
またそのテンプレートファイル名が node.tpl.php であることを指定している。
• 特に指定がない場合はデフォルトで関数という扱いになる
45. (参考)独自のテーマ関数の定義例
• 自作のモジュールでテーマ関数を作成する例
– 独自のテーマ関数を作成するには hook_theme() API を利用する
– 実装例
function mymodule_theme() {
return array(
'mythemehook' => array(
'variables' => array('parameter' => NULL),
),
);
}
?>
<?php
function theme_mythemehook($variables) {
$parameter = $variables['parameter'];
if (!empty($parameter)) {
return '<div class="my-theme-hook">' . $parameter . '</div>';
}
}
?>
hook_theme() をオーバーライドして連想配列でテーマ関数を定義する。
46. テーマ関数の呼び出し
• テーマ関数の呼び出しには theme() API を利用する
– theme() 経由で呼び出すことでオーバーライドが可能になる
• theme() API は命名規則に基づいて該当する関数を探索して呼び出す
– 古い PHP でも OOP の仮想関数のような動作を実現するための手法
• 例)theme_image() を呼び出すには・・・
• 定義したテーマ関数を直接呼び出すとオーバーライドできなくなるので注意
– 直接呼び出すと(当然ながら)常にその関数自体が呼び出されてしまう
– したがって、その呼び出し部分はテーマ側でオーバーライドできなくなる
» テーマ関数として定義した意味がなくなる
» 意図的に常にデフォルト実装が呼び出されるようにしたい場合は別
<?php print theme('image',
array('path' => 'path/to/image.png',
'alt' => 'Image description')); ?>
47. テンプレートとテーマ関数の suggestion
• suggestion とは?
– 名前のパターンで代替テンプレート/テーマ関数を判別する仕組み
• 種々の条件に対応するテンプレートファイル名のパターンが定義されている
– 条件成立時に、対応するパターンにマッチする名前のテンプレートファイルがあれば、
そのファイルがデフォルトのテンプレートの代わりに使用される
– Drupal 7 の suggestion の一覧
• https://drupal.org/node/1089656
種々の条件に対応して
適用されるテンプレートの候補を
ファイル名パターンとして提示します
ブロックのテンプレートなら・・・
48. 例)ブロックテンプレートの suggestion
• ブロックのコンテンツ生成時に使用されるテンプレート
– block.tpl.php
• ブロックモジュールのデフォルト実装
– block--REGION.tpl.php
• REGION にはテーマのリージョン名が入る。この名前のファイルがテーマのディレクトリにあると、
対応するリージョンのブロックにはそのテンプレートファイルが適用される。
– block--MODULE.tpl.php
• MODULE にはブロックを作成するモジュール名が入る。
• たとえば、menu モジュールが作成したブロックに適用するテンプレートファイルは、
block--menu.tpl.php となる。
– block--MODULE--DELTA.tpl.php
• DELTA は、モジュールが付けたブロックのシステム名(以前の Drupal では番号だった)
• たとえば、system モジュールが作成した navigation ブロックに適用されるテンプレートファイルは、
block--system--navigation.tpl.php となる。
優先順位は下に書かれているものほど高くなります。
条件に該当するものが複数ある場合は、リストのより下位のパターンにマッチするものが適用されます。
49. 例)ページテンプレートの suggestion
• ページの suggestion は引数に基づくパターンになる
– ここでの引数とはページパスの構成要素のこと
• 例)http://example.com/node/1 の場合、最初の引数が node、2番目の引数が 1 となる
パス 最初の候補 次の候補 その次の候補 デフォルト実装
node → page--front.tpl.php → → → page--node.tpl.php → page.tpl.php
node/1 → page--node--1.tpl.php → page--node--%.tpl.php → page--node.tpl.php → pgae.tpl.php
user/1 → page--user--1.tpl.php → page--user--%1.tpl.php → page--user.tpl.php → page.tpl.php
hoge/fuga → page--hoge--fuga.tpl.php → → → page--hoge.tpl.php → page.tpl.php
hoge/1 → page--hoge--1.tpl.php → page--hoge--%.tpl.php → page--hoge.tpl.php → page.tpl.php
↓ ↓ ↓ ↓
両方の引数にマッチしたときに
適用される
% は数字の第2引数のワイル
ドカードを表すプレースホルダ。
第1引数がマッチし、数字の第
2引数が存在するときに適用さ
れる。
第1引数がマッチした場
合で、それ以外に該当す
るテンプレートファイルが見
つからないときに適用され
る。
デフォルトのテンプ
レートファイル。該
当する特定条件
のテンプレートが見
つからない場合に
適用される。
※ hoge、fuga には任意の文字列が入ります
50. 例)テーマ関数の suggestion
• テーマ関数にも関数名パターンによる suggestion がある
• 例)theme_links の場合
– THEME_links()
• 他にマッチする実装が見つからないときに適用されるデフォルト実装
– THEME_links__node()
• ノード内のリンク一覧にのみ適用される theme_links() の実装
– THEME_links__comment()
• コメント内のリンク一覧にのみ適用される theme_links() の実装
– THEME_links__contextual()
• コンテキストリンク用に生成されるリンクにのみ適用される theme_links() の実装
– THEME_links__contextual__node()
• ノード内のコンテキストリンクにのみ適用される theme_links() の実装
※ THEME の部分にはテーマの内部名が入ります
※上記のコンテキストリンクとは、コアの Contextual links モジュールが生成するリンクのことです
Editor's Notes Twig/D8 について
http://twig.sensiolabs.org/
https://drupal.org/node/2008464 https://drupal.org/node/171194 この後に、テーマ関数オーバーライドの実習を入れたい https://drupal.org/node/223440