WordPress: 種類毎に選択されるテンプレート名の一覧を調べてみた

WordPressはブラウザからの要求を解析して使用するテンプレートを判定します。
しかし名前つけの法則が複雑で、テーマの作成者側からするとわかり難いのが困りものです。
そこで、テンプレート名について調べてみました。

テンプレート選択の流れ

WordPressは、まずはＵＲＬを解析して表示するWebページの種類を判断します。
判断結果は、is_home()などの判定関数で確認します。

次に下表の順番で、判定関数を実行します。

順番 ページタイプ 判定関数 ファイル名候補
1 埋め込み投稿ページ is_embed()
  1. embed-{$object->post_type}-{$post_format}.php
  2. embed-{$object->post_type}.php
  3. embed.php
2 404ページ is_404() 404.php
3 検索ページ is_search() search.php
4 フロントページ is_front_page() front-page.php
5 ホーム（トップ）
ページ		 is_home()
  1. home.php
  2. index.php
6 プライバシー
ポリシー		 is_privacy_policy() privacy-policy.php
7 投稿タイプの
アーカイブページ		 is_post_type_archive()
  1. archive-{$post_type}.php
  2. archive.php
8 カスタムタクソノミー
ページ		 is_tax()
  1. taxonomy-$taxonomy-{$slug_decoded}.php
  2. taxonomy-$taxonomy-{$term->slug}.php
  3. taxonomy-$taxonomy.php
  4. taxonomy.php
9 添付ファイルページ is_attachment()
  1. {$type}-{$subtype}.php
  2. {$subtype}.php
  3. {$type}.php
  4. attachment.php
10 投稿ページ is_single()
  1. get_post_meta( $post->ID, '_wp_page_template', true )の結果
  2. single-{$object->post_type}-{$name_decoded}.php
  3. single-{$object->post_type}-{$object->post_name}.php
  4. single-{$object->post_type}.php
  5. single.php
11 固定ページ is_page()
  1. get_post_meta( $post->ID, '_wp_page_template', true )の結果
  2. page-{$pagename_decoded}.php
  3. page-{$pagename}.php
  4. page-{$id}.php
  5. page.php
12 投稿・固定・
添付ファイルページ		 is_singular() singular.php
13 カテゴリーページ is_category()
  1. category-{$slug_decoded}.php
  2. category-{$category->slug}.php
  3. category-{$category->term_id}.php
  4. category.php
14 タグページ is_tag()
  1. tag-{$slug_decoded}.php
  2. tag-{$tag->slug}.php
  3. tag-{$tag->term_id}.php
  4. tag.php
15 投稿者ページ is_author()
  1. author-{$author->user_nicename}.php
  2. author-{$author->ID}.php
  3. author.php
16 日付アーカイブページ is_date() date.php
17 カテゴリー・タグ・
投稿者・日付
アーカイブページ		 is_archive()
  1. archive-{$post_type}.php
  2. archive.php
18 index.php

判定関数がtrueを返したら、ファイル名候補に挙げてあるファイルが存在するかを順番に確認します。

子テーマに対応するために、次の順番でディレクトリを検索します。
つまり、一つのファイルに対して最高3回存在チェックをしています。

■子テーマが存在する場合
  1. 子テーマディレクトリ
  2. 親テーマディレクトリ
  3. /wp-includes/theme-compat/
■子テーマが存在しない場合
  1. テーマディレクトリ
  2. /wp-includes/theme-compat/

子テーマについて、少し調べてみました。次の記事を読んでみてください。

WordPress: 子テーマの仕組みについて調べてみた

ファイルが存在していたら、そのファイルが目的のテンプレートファイルです。
以降のチェックは行いません。

全てのパターンに一致しない場合は、最後の index.php が選択されます。

簡単な解説

前項の表中のファイル名候補は、WordPressのソースコードでの表記を記述してあります。
わかり難い部分を捕捉します。

埋め込み投稿ページ

順番 ページタイプ 判定関数 ファイル名候補
1 埋め込み投稿ページ is_embed()
  1. embed-{$object->post_type}-{$post_format}.php
  2. embed-{$object->post_type}.php
  3. embed.php

embedは、Webページ内に埋め込む目的で呼び出されます。
ＵＲＬ貼り付けで表示されるリンクカードなどがembedです。

ファイル名候補の一部は、次の規則で置き換えられます。

  • $object->post_type
    投稿タイプ。'post'や'page'など。
  • $post_format
    投稿のフォーマット。'link'や'image'など。
    テーマ毎に有効化されている必要がある。

    投稿のフォーマットとは、テーマTwenty Seventeenの投稿ページにある次のような選択。
    投稿のフォーマット

投稿タイプのアーカイブページ

順番 ページタイプ 判定関数 ファイル名候補
7 投稿タイプの
アーカイブページ		 is_post_type_archive()
  1. archive-{$post_type}.php
  2. archive.php

投稿タイプごとの一覧ページです。

ファイル名候補の一部は、次の規則で置き換えられます。

  • $object->post_type
    投稿タイプ。'post'や'page'など。

カスタムタクソノミーページ

順番 ページタイプ 判定関数 ファイル名候補
8 カスタムタクソノミー
ページ		 is_tax()
  1. taxonomy-$taxonomy-{$slug_decoded}.php
  2. taxonomy-$taxonomy-{$term->slug}.php
  3. taxonomy-$taxonomy.php
  4. taxonomy.php

カスタムタクソノミーのページです。

ファイル名候補の一部は、次の規則で置き換えられます。

  • $taxonomy
    タクソノミー名。
  • $term->slug
    スラッグ。
  • $slug_decoded
    $term->slugをurldecode()の引数として実行した結果。

添付ファイルページ

順番 ページタイプ 判定関数 ファイル名候補
9 添付ファイルページ is_attachment()
  1. {$type}-{$subtype}.php
  2. {$subtype}.php
  3. {$type}.php
  4. attachment.php

アップロードした画像やファイルのページです。
※ファイルへのＵＲＬではありません。添付ファイルページのＵＲＬはメディアライブラリで確認できます。

ファイル名候補の一部は、次の規則で置き換えられます。

  • $type
    'image/png' などのMIMEタイプの '/' より前の部分
  • $subtype
    'image/png' などのMIMEタイプの '/' より後ろの部分

投稿ページ

順番 ページタイプ 判定関数 ファイル名候補
10 投稿ページ is_single()
  1. get_post_meta( $post->ID, '_wp_page_template', true )の結果
  2. single-{$object->post_type}-{$name_decoded}.php
  3. single-{$object->post_type}-{$object->post_name}.php
  4. single-{$object->post_type}.php
  5. single.php

投稿記事のページです。

ファイル名候補の一部は、次の規則で置き換えられます。

  • get_post_meta( $post->ID, '_wp_page_template', true )の結果
    データベースのpost_metaテーブルから、_wp_page_templateの値を取得した結果
  • $object->post_type
    'post'などの投稿タイプ
  • $object->post_name
    投稿名
  • $name_decoded
    $object->post_nameをurldecode()の引数として実行した結果。

固定ページ

順番 ページタイプ 判定関数 ファイル名候補
11 固定ページ is_page()
  1. get_post_meta( $post->ID, '_wp_page_template', true )の結果
  2. page-{$pagename_decoded}.php
  3. page-{$pagename}.php
  4. page-{$id}.php
  5. page.php

固定記事のページです。

ファイル名候補の一部は、次の規則で置き換えられます。

  • get_post_meta( $post->ID, '_wp_page_template', true )の結果
    データベースのpost_metaテーブルから、_wp_page_templateの値を取得した結果
  • $pagename
    固定記事名
  • $name_decoded
    $pagenameをurldecode()の引数として実行した結果。
  • $id
    固定記事のID。

カテゴリーページ

順番 ページタイプ 判定関数 ファイル名候補
13 カテゴリーページ is_category()
  1. category-{$slug_decoded}.php
  2. category-{$category->slug}.php
  3. category-{$category->term_id}.php
  4. category.php

カテゴリーのページです。

ファイル名候補の一部は、次の規則で置き換えられます。

  • $category->slug
    カテゴリーのスラッグ
  • $slug_decoded
    $category->slugをurldecode()の引数として実行した結果。
  • $category->term_id
    カテゴリーのID

タグページ

順番 ページタイプ 判定関数 ファイル名候補
14 タグページ is_tag()
  1. tag-{$slug_decoded}.php
  2. tag-{$tag->slug}.php
  3. tag-{$tag->term_id}.php
  4. tag.php

タグのページです。

ファイル名候補の一部は、次の規則で置き換えられます。

  • $tag->slug
    タグのスラッグ
  • $name_decoded
    $tag->slugをurldecode()の引数として実行した結果。
  • $tag->term_id
    タグのID

投稿者ページ

順番 ページタイプ 判定関数 ファイル名候補
15 投稿者ページ is_author()
  1. author-{$author->user_nicename}.php
  2. author-{$author->ID}.php
  3. author.php

投稿者のページです。

ファイル名候補の一部は、次の規則で置き換えられます。

  • $author->user_nicename
    投稿者のニックネーム
  • $author->ID
    投稿者のID

カテゴリー・タグ・投稿者・日付アーカイブページ

17 カテゴリー・タグ・
投稿者・日付
アーカイブページ		 is_archive()
  1. archive-{$post_type}.php
  2. archive.php

カテゴリーやタグなどのカテゴリ系ページの表示で、個々のテンプレートが存在しない場合に呼び出されます。

ファイル名候補の一部は、次の規則で置き換えられます。

  • $post_type
    投稿タイプ

その他のテンプレート

WordPressにはheader.phpやfooter.phpなど、ここまで紹介していないテンプレートがあります。
これらはテンプレート選択の流れで挙げているテンプレート内で、対応する関数を呼び出すことで組みこまれます。

呼び出し関数 引数 ファイル名候補 アクション
get_header() $name = null, $args = array()
  1. header-{$name}.php
  2. header.php
 get_header
get_footer() $name = null, $args = array()
  1. footer-{$name}.php
  2. footer.php
 get_footer
get_search_form() $args = array()
  1. searchform.php
  2. get_search_form()内に記述されているhtmlタグ
 pre_get_search_form
get_sidebar() $name = null, $args = array()
  1. sidebar-{$name}.php
  2. sidebar.php
 get_sidebar

引数$argは、load_template()関数に渡されます。
ファイル名候補の$nameは、引数の$nameです。

アクションは、テンプレートの読み込み前に実行されます。
また、呼び出し関数と同じ引数を受け付けます。

自作テンプレートの読み込み

WordPressで定義されていない自作のテンプレートは、get_template_part()関数で読み込みます。
この関数も、子テーマに対応しています。

呼び出し関数 引数 ファイル名候補 アクション
get_template_part() $slug, $name = null, $args = array()
  1. {$slug}-{$name}.php
  2. {$slug}.php
 get_template_part_{$slug}

この関数は、テンプレートの読み込み前に次の二つのアクションを実行します。

  1. get_template_part_{$slug}
    引数：$slug, $name, $args
  2. get_template_part
    引数：$slug, $name, $templates, $args

$slug, $name, $argsはget_template_part()の引数で、$templatesは読み込み予定のテンプレート名です。