WordPress Logo WordPress テンプレート関係の関数

更新日:2019年02月19日

作成日:2019年02月07日

テンプレートの読み込みを行う関数

WordPress では、投稿などのデータベースに格納されたデータをテンプレート(ページの雛形)を使って表示します。

一般的な Web サイトの構造は、ヘッダー、コンテンツ部分、サイドバー、フッターなどから構成されています。WordPress でサイトを作成する際にページごとにテンプレートを作成していくと、ヘッダーやフッターなどの共通部分を繰り返し記述することになってしまいます。

このため、共通の部分(パーツ)は header.php、content.php、sidebar.php、footer.php などの「テンプレートパーツ」と呼ばれるテンプレートファイルに記述して、各テンプレートでそれぞれのテンプレートパーツを読み込むようにします。

テンプレートパーツを読み込む関数を「インクルードタグ」と呼びます。また、テンプレートパーツは「パーツテンプレート」や「モジュールテンプレート」と呼ばれることもあります。

インクルードタグは wp-includes/general-template.php で定義されています。

テンプレートパーツ

WordPress では、ページのテンプレートを以下のようなテンプレートパーツに分割して管理します。

  • ヘッダー:header.php
  • コンテンツ部分:content.php
  • サイドバー:sidebar.php
  • フッター:footer.php

以下は、テンプレートパーツによる分割の概念図です。

テンプレートパーツによる分割の概念図

以下は、テンプレートパーツの読み込みの概念図です。

テンプレートパーツの読み込みの概念図

テンプレートパーツ(テンプレートファイル)とそのインクルードタグ
パーツ ファイル名 読み込むためのインクルードタグ
ヘッダー header.php <?php get_header(); ?>
header-{name}.php(※1) <?php get_header($name); ?>
フッター footer.php <?php get_footer(); ?>
footer-{name}.php(※1) <?php get_footer($name); ?>
サイドバー sidebar.php <?php get_sidebar(); ?>
sidebar-{name}.php(※1) <?php get_sidebar($name); ?>
検索フォーム searchform.php <?php get_search_form(); ?>
コメント comments.php <?php comments_template(); ?>
カスタム aaa.php(※2) <?php get_template_part('aaa'); ?>
aaa-bbb.php(※2) <?php get_template_part('aaa', 'bbb'); ?>

(※1)ヘッダー、フッター、サイドバーのテンプレートパーツで名前(name)を指定すると、指定したテンプレートパーツ header-{name}.php(ヘッダーの場合) を読み込みます。

(※2)任意のテンプレートパーツを読み込む場合は、get_template_part() を使用します。

以下はインクルードタグを使ったテンプレートの例です(_s テーマの index.php から引用) 。

2行目、20行目、25行目、及び32、33行目でインクルードタグが使われています。

<?php
get_header();  //header.php の読み込み
?>
<div id="primary" class="content-area">
  <main id="main" class="site-main">
    <?php
    if ( have_posts() ):
      if ( is_home() && !is_front_page() ):
        ?>
    <header>
      <h1 class="page-title screen-reader-text">
        <?php single_post_title(); ?>
      </h1>
    </header>
    <?php
      endif;
      while ( have_posts() ):
        the_post();
        //template-parts フォルダ内の content-xxxx.php の読み込み
        //xxxx は get_post_type の値
        get_template_part( 'template-parts/content', get_post_type() );
      endwhile;
        the_posts_navigation();
    else :
      //template-parts フォルダ内の content.php の読み込み
      get_template_part( 'template-parts/content' );
    endif;
    ?>
  </main>
  <!-- #main -->
</div> <!-- #primary -->
<?php
get_sidebar();  //sidebar.php の読み込み
get_footer();  //footer.php の読み込み

以下はインクルードタグの1つ get_header() のソースです。

function get_header( $name = null ) {
  /**
   * Fires before the header template file is loaded.
   *
   * @since 2.1.0
   * @since 2.8.0 $name parameter added.
   *
   * @param string|null $name Name of the specific header file to use. null for the default header.
   */
  do_action( 'get_header', $name );

  $templates = array();
  $name = (string) $name;
  if ( '' !== $name ) {
    $templates[] = "header-{$name}.php";
  }

  $templates[] = 'header.php';

  locate_template( $templates, true );
}

最初に get_header アクション フックが実行されています。そして $name が指定されていれば header-{$name}.php を変数 $templates(配列)に追加し、その後 header.php を追加しています。

最後に、locate_template() を使って変数 $templates に入っている名前のファイルを読み込んでいます。locate_template() は指定された名前のファイルを探して読み込む関数です。

現在のテーマのディレクトリに header.php がなければ、wp-includes/theme-compat/ の中を探します。wp-includes/theme-compat/ の中には、デフォルトテーマの header.php、footer.php、sidebar.php などが入っているので、この header.php が読み込まれることになります。

以下はテンプレートの読み込みを行う関数やそれに関連する関数です。

get_header

テーマのヘッダー(header.php テンプレートファイル)を読み込みます。名前(name)を指定すると、指定したヘッダー header-{name}.php を読み込みます。

header.php または header-{name}.php がテーマに含まれていない場合は、デフォルトテーマの wp-includes/theme-compat/header.php を読み込みます。

get_header( $name )

パラメータ
$name(文字列):(オプション)指定した場合は header-name.php($name が name の場合)を読み込みます。
戻り値
なし

複数のヘッダー(テンプレートパーツ)の使い分け

ヘッダー部分を複数用意し、組み込み先のテンプレートに応じてヘッダー部分を切り替えることができます。

  • テーマ内に「header-xxxx.php」のような名前のヘッダーテンプレートパーツを複数用意
  • 条件分岐タグを使ってテンプレートにより get_header('xxxx') と記述して読み込む

以下の場合、header-home.php と header-404.php を用意しておき、

  • ホームの場合は header-home.php を、
  • 404ページの場合は header-404.php を、
  • その他の場合は header.php
を読み込む例です。

<?php
if ( is_home() ) :  //ホームの場合
  get_header('home');  //header-home.php
elseif ( is_404() ) :  //404ページの場合
  get_header('404');  //header-404.php
else :  //その他の場合
  get_header();  //header.php
endif;
?>

get_sidebar

テーマのサイドバー(sidebar.php テンプレートファイル)を読み込みます。 名前 ($name) を指定すると、対応するサイドバー sidebar-{name}.php を読み込みます。

sidebar.php または sidebar-{name}.php がテーマに含まれていない場合は、デフォルトテーマの wp-includes/theme-compat/sidebar.php からサイドバーを読み込みます。

get_sidebar( $name )

パラメータ
$name(文字列):(オプション)指定した場合は sidebar-name.php($name が name の場合)を読み込みます。
戻り値
なし

左右2つのサイドバーを配置する例

sidebar-right.php と sidebar-left.php を用意して、以下のように読み込みます。

<?php get_header(); ?>
<?php get_sidebar('left'); ?>
<?php get_sidebar('right'); ?>
<?php get_footer(); ?>

複数のサイドバー(テンプレートパーツ)の使い分け

サイドバー部分を複数用意し、組み込み先のテンプレートに応じてサイドバー部分を切り替えることができます。

  • テーマ内に「sidebar-xxxx.php」のような名前のサイドバーテンプレートパーツを複数用意
  • 条件分岐タグを使ってテンプレートにより get_sidebar('xxxx') と記述して読み込む

以下の場合、sidebar-home.php と sidebar-404.php を用意しておき、

  • ホームの場合は sidebar-home.php を、
  • 404ページの場合は sidebar-404.php を、
  • その他の場合は sidebar.php
を読み込む例です。

<?php
if ( is_home() ) :  //ホームの場合
  get_sidebar('home');  //sidebar-home.php
elseif ( is_404() ) :  //404ページの場合
  get_sidebar('404');  //sidebar-404.php
else :  //その他の場合
  get_sidebar();  //sidebar.php
endif;
?>

get_search_form

テーマの searchform.php ファイルを使用して検索フォームを表示します。テーマに searchform.php ファイルがない場合は WordPress に組み込みの検索フォームを表示します。

get_search_form( $echo )

パラメータ
$echo(真偽値):(オプション) true ならフォームを表示します。false なら表示せずフォームを文字列として返します。初期値: true
戻り値
パラメータ $echo が false ならフォームの HTML を返します。

テンプレートに以下を記述すれば、その場所に検索フォームが表示されます。

<?php get_search_form(); ?>

テーマに searchform.php ファイルがない場合は以下のような WordPress デフォルトの検索フォームが読み込まれます。

<!-- HTML4 フォーム -->
<form role="search" method="get" id="searchform" class="searchform" action="<?php echo esc_url( home_url( '/' ) ); ?>">
  <div>
    <label class="screen-reader-text" for="s"><?php _x( 'Search for:', 'label' ); ?></label>
    <input type="text" value="<?php echo get_search_query(); ?>" name="s" id="s" />
    <input type="submit" id="searchsubmit" value="<?php echo esc_attr_x( 'Search', 'submit button' ); ?>" />
  </div>
</form>
          
<!-- HTML5 フォーム -->
<form role="search" method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
  <label>
    <span class="screen-reader-text"><?php echo _x( 'Search for:', 'label' ) ?></span>
    <input type="search" class="search-field" placeholder="<?php echo esc_attr_x( 'Search …', 'placeholder' ) ?>" value="<?php echo get_search_query() ?>" name="s" title="<?php echo esc_attr_x( 'Search for:', 'label' ) ?>" />
  </label>
  <input type="submit" class="search-submit" value="<?php echo esc_attr_x( 'Search', 'submit button' ) ?>" />
</form>

HTML5 フォームを表示させるには、以下を functions.php に記述します。

add_theme_support( 'html5', array( 'search-form' ) );
独自の検索フォームの設置

検索フォームをカスタマイズしたい場合は、検索フォームのテンプレートパーツ searchform.php を独自に作成します。

  • 検索キーワードを入力するテキストボックスの name 属性 を s と指定します。(必須)
  • the_search_query() を利用して検索結果ページに検索キーワードを出力します。
  • アクセシビリティのために、form 要素に role 属性(値:search )を指定し、入力するテキストボックスに aria-label 属性でラベルを付けます。

name 属性 を s とすることで submit ボタンをクリックすると get メソッドでテキストボックスに入力された値が検索キーワードとして送信されます。

以下は searchform.php の例です。

<form role="search" method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
  <input type="search" class="search-field" placeholder="検索" value="<?php the_search_query(); ?>" name="s" aria-label="このサイトで検索">
  <input type="submit" class="search-submit" value="検索">
</form>

以下は、input 要素の代わりに button 要素とアイコンフォント(Fontawesome のための i 要素を使う例です。この場合、i 要素は単に装飾目的なので aria-hidden="true" を指定しています。

また、前述の例では action 属性の値は home_url()エスケープ処理して出力していますが、この例では空にしています。(form タグの action 属性

<form role="search" method="get" class="search-form" action="">
  <input type="search" class="search-field" placeholder="検索" value="<?php the_search_query(); ?>" name="s" aria-label="このサイトで検索">
  <button type="submit" class="search-submit">
    <i class="fas fa-search" aria-hidden="true"></i> 検索
  </button>
</form>

検索結果に投稿だけを表示

検索結果に投稿だけを(固定ページ等を除外して)表示したい場合は、下記の input 要素をフォームに追加します(type="hidden" を指定しているので表示されません)。

post_type のデフォルト値は any で、投稿・固定ページ・カスタム投稿タイプを意味しますが、以下のように value 属性の値を post とすることで投稿だけを対象にすることができます。

<input type="hidden" value="post" name="post_type" id="post_type" />

get_search_form アクションを使う例

カスタム関数を functions.php に記述して、その関数を get_search_form アクションにフックする方法もあります。以下は例です。この場合、searchform.php が存在していてもこちらの記述が優先されます。

function my_search_form( $form ) {
  $form = '<form role="search" method="get" class="search-form" action="'.esc_url( home_url( '/' ) ).'">
    <input type="search" class="search-field" placeholder="検索" value="'.the_search_query().'" name="s" aria-label="このサイトで検索">
    <input type="submit" class="search-submit" value="検索">
  </form>';
  return $form;
}
add_filter( 'get_search_form', 'my_search_form' );
検索結果の表示

検索結果はテンプレート search.php を使って表示することができます。search.php でループを記述すると、取得された検索結果を出力できるようになっています。

ユーザーが入力した検索キーワードは the_search_query() で出力することができますが、この関数は属性値に出力するようにエスケープ処理されているので、以下のように get_search_query() で取得した値を esc_html() でエスケープして出力しています。

また、以下の例では、検索キーワードに該当する記事がない場合の処理(検索フォームの再表示)も記述してあります。

<?php get_header(); ?>
<div class="contents">
  <div class="search_results">
    <!-- ループ -->
    <?php if(have_posts()): ?>
    <!-- 検索キーワードに該当する記事がある場合の処理 -->
    <!-- 検索キーワードを出力 -->
    <h2>検索結果:「<?php echo esc_html( get_search_query( false ) ); ?>」</h2>
    <?php while(have_posts()): the_post(); ?>
    <!-- 該当する記事のタイトルにリンクを付けて表示 -->
    <?php the_title( '<h3><a href="'.esc_url( get_permalink()).'">', '</a></h3>'); ?>
    <!-- 該当する記事の抜粋を表示 -->
    <div class="excerpt">
      <?php the_excerpt(); ?>
      <p><a href="<?php the_permalink(); ?>">続きを読む</a></p>
    </div><!-- end of .excerpt -->
    <?php endwhile; ?>
    <?php else: ?>
    <!-- 検索キーワードに該当する記事がない場合の処理-->
    <!-- 検索キーワードを出力-->
    <h2>「<?php echo esc_html( get_search_query( false ) ); ?>」の検索結果が見つかりませんでした。</h2>
    <p>別のキーワードでお試しください。</p>
    <!-- 検索フォームを表示-->
    <?php get_search_form(); ?>
    <?php endif;  ?>
  </div><!-- end of .search_results -->
</div> <!-- end of .content -->

the_search_query

検索が行われた時に入力された文字列(検索キーワード)を表示します。この関数は HTML 属性の中で出力する場合は安全です(エスケープ処理は esc_attr() が使用されています)。

the_search_query()

パラメータ
なし
戻り値
なし

検索フォームに入力された検索キーワードを input 要素の value 属性に出力する例です。

<input type="search" value="<?php the_search_query(); ?>" name="s">

HTML に出力する場合は、以下のように get_search_query()esc_html() を使って出力します。

esc_html() と esc_attr() は機能的には同じなので、どちらでも問題はないと思いますが、出力される際に適用されるフィルターが異なります。

<h2>検索結果:「<?php echo esc_html( get_search_query( false ) ); ?>」</h2>

以下がソースです。

get_search_query() で取得した値に the_search_query フィルターを適用し、esc_attr() でエスケープ処理して出力しています。

function the_search_query() {
  /**
   * Filters the contents of the search query variable for display.
   *
   * @since 2.3.0
   *
   * @param mixed $search Contents of the search query variable.
   */
  echo esc_attr( apply_filters( 'the_search_query', get_search_query( false ) ) );
}

get_search_query

検索フォームで入力された検索キーワードを取得します。引数に false を指定して取得した値を出力する場合はエスケープ処理が必要です。

get_search_query( $escaped )

パラメータ
$escaped(真偽値):(オプション) 結果をエスケープするかどうか。デフォルトは true でエスケープします。false を指定した場合は後でエスケープする必要があります。 初期値: true
戻り値
検索フォームでユーザが入力した検索キーワード(文字列)

検索キーワードを出力する例です。

<p>「<?php echo esc_html( get_search_query( false ) ); ?>」の検索結果が見つかりませんでした。</p>

以下がソースです。

get_query_var() で取得した値に get_search_query フィルタを適用して、$escaped が true の場合は esc_attr() でエスケープ処理しています。

function get_search_query( $escaped = true ) {
  /**
    * Filters the contents of the search query variable.
    *
    * @since 2.3.0
    *
    * @param mixed $search Contents of the search query variable.
  */
  $query = apply_filters( 'get_search_query', get_query_var( 's' ) );

  if ( $escaped )
    $query = esc_attr( $query );
  return $query;
}

comments_template

コメントテンプレートを読み込みます。comments.php がテーマに含まれていない場合は、デフォルトテーマの wp-includes/theme-compat/comments.php から読み込みます。

投稿(post)か固定ページ(page)以外のページから呼ばれた場合はコメントは表示されません(single.php または page.php で使用します)。

comments_template( $file, $separate_comments )

パラメータ
  • $file(string):(オプション)読み込むコメントテンプレートファイルを指定します。先頭に「/」を付けて指定します。初期値: /comments.php
  • $separate_comments(boolean):(オプション)タイプによりコメントを分離するかどうかの真偽値。区切る場合は true、区切らない場合は false。初期値: false
戻り値
なし

comments.php 以外のテンプレートを読み込むときは、comments_template() の第1引数にファイル名を指定します。

<?php comments_template('/single_comments.php'); ?>

get_template_part

任意のテンプレートファイルを読み込みます。一致するテンプレートファイルが見つからない場合に警告を出しません。

get_template_part( $slug, $name )

パラメータ
  • $slug(文字列):(必須) テンプレートのスラッグ名
  • $name(文字列):(オプション) 特定テンプレートの名前
戻り値
なし

第一引数(スラッグ名)で、組み込むテンプレートファイルの名前を指定します(拡張子 .php は付けません)。以下は「content.php」というテンプレートを組み込む例です。

<?php get_template_part('content'); ?> 

第二引数(名前)も指定すると、「スラッグ名 - 名前.php」のテンプレートがあればそのファイルを組み込み、なければ「スラッグ名.php」を組み込みます。

以下の場合、「content-page.php」があればそれを組み込み、なければ「content.php」を組み込みます。

<?php get_template_part( 'content', 'page' ); ?>

上記の場合、get_template_part('content-page') と記述しても「content-page.php」を組み込むことはできますが「content-page.php」がない場合に「content.php」を組み込みません。

また、$slug はアクションフック get_template_part_{$slug} で利用できるので(挿入時に割り込み処理ができる単位なので)、テンプレートファイルの種類ごとに slug を分けておくと便利になります。

サブフォルダにファイルがある場合は、そのパスを指定します。parts フォルダにある content-page.php を組み込む場合は以下のように記述します。

<?php get_template_part( 'parts/content', 'page' ); ?>

以下がソースです。

最初にアクションフック get_template_part_{$slug} が実行されます。

$name が指定されていれば、配列の変数 $templates に {$slug}-{$name}.php と言うファイル名を格納し、続いて変数 $templates に {$slug}.php と言うファイル名を格納しています。

変数 $templates を引数にして locate_template() を実行してファイルを読み込みます。locate_template() は引数に与えられたファイル名の配列を使って順番にファイルを検索して、ファイルが見つかれば読み込みます。

locate_template() の内部ではファイルを読み込むために load_template() が呼び出されています。

function get_template_part( $slug, $name = null ) {
  /**
   * Fires before the specified template part file is loaded.
   *
   * The dynamic portion of the hook name, `$slug`, refers to the slug name
   * for the generic template part.
   *
   * @since 3.0.0
   *
   * @param string      $slug The slug name for the generic template.
   * @param string|null $name The name of the specialized template.
   */
  do_action( "get_template_part_{$slug}", $slug, $name );

  $templates = array();
  $name = (string) $name;
  if ( '' !== $name )
    $templates[] = "{$slug}-{$name}.php";

  $templates[] = "{$slug}.php";

  locate_template($templates, true, false);
}
テンプレートパーツで変数を参照

get_template_part() などの関数で読み込まれたテンプレートパーツは、その内部からは呼び出し元で定義された変数を参照できません(PHP の言語仕様上、関数の外のスコープを参照することができない)。

WordPress の関数を使わずに、直接 PHP の include や require を使ってインクルードすれば読み込まれた側でも変数を参照できますが、通常テンプレートファイルを読み込む場合(functions.php は別ですが)、このような使い方はしません。

<?php 
  $my_val = "My Value";
  include(get_theme_file_path('content-test.php'));
?>

解決策としては、呼び出し元で set_query_var() を使って変数をテンプレートパーツで使えるようにし、テンプレートパーツ側で get_query_var() を使って参照します(テンプレートに変数を渡す)。

呼び出し元のファイルで set_query_var() の第一引数に参照する値の「キー名」を指定し、第二引数に参照したい「値」を指定します。

//呼び出し元ファイル
<?php 
  set_query_var( 'my_val', "My Value !"); 
  get_template_part('content', 'page');
?>

テンプレートパーツ側では get_query_var() の引数に、set_query_var() で指定した「キー名」を指定します。

//content-page.php (読み込まれるテンプレートパーツ)
<p><?php echo get_query_var('my_val'); ?></p>

//以下が出力されます
//My Value ! 

set_query_var

メインクエリの指定したクエリ変数に値をセットします。

set_query_var( $var, $value )

パラメータ
  • $var(文字列):(必須) クエリ変数を指定するキー。
  • $value(mixed):(必須) クエリ変数にセットする値。
戻り値
なし

set_query_var は グローバル $wp_query オブジェクトのメソッド set を使用するラッパー関数です。以下がソースです。

function set_query_var( $var, $value ) {
  global $wp_query;
  $wp_query->set( $var, $value );
}

get_template_part() 関数で読み込まれたテンプレートパーツで、呼び出し元で定義された変数を参照する場合などに使用します。

// get_template_part() で my-template.php を読み込む側のファイル
set_query_var('my_postid', $post->ID);
get_template_part('my-template');
// my-template.php で呼び出し元で定義した変数を参照
$my_postid = get_query_var('my_postid');  //呼び出し元の投稿 ID

get_query_var

$wp_query に格納されているプロパティ query_vars から指定したキーの値を取得するための関数です。

get_query_var( $var, $default )

パラメータ
  • $var(string):(必須)取得する変数のキー(変数名)
  • $default(mixed):(オプション)変数が設定されていない(存在しない)場合に戻す値。初期値: 空の文字列
戻り値
指定された変数の値。変数が設定されていない場合は $default を返します。

以下がソースです。

function get_query_var( $var, $default = '' ) {
  global $wp_query;
  return $wp_query->get( $var, $default );  //$wp_query の get() メソッド
}

locate_template

指定されたテンプレートファイルが存在するか確認し、見つかればテンプレートのファイル名を返します。パラメータ $load が true の場合は、見つかったテンプレートファイルを読み込みます。

locate_template( $template_names, $load, $require_once )

パラメータ
  • $template_names(文字列|配列):(必須) 検索するテンプレートファイルを優先度順に並べた配列または文字列。(拡張子が必要。)
  • $load(真偽値):(オプション) true を指定すると、見つかったテンプレートファイルを読み込みます。初期値: false
  • $require_once(真偽値):(オプション) true なら PHP の require_once 関数でテンプレートファイルを読み込みます。false なら PHP の require 関数を使います。$load が false(デフォルト)の時は無視されます。 初期値: true
戻り値
見つかればテンプレートのパスを含むファイル名を返し、見つからなければ空文字列を返します。

以下がソースです。$template_names で指定されたファイルを file_exists() で順番に検索します。また、検索するディレクトリは以下の順になっていて、そのディレクトリにファイルが存在すればそのファイルを変数 $located に格納します。

  1. STYLESHEETPATH(現在のテーマまたは子テーマのスタイルシートのディレクトリ)
    get_stylesheet_directory() で取得するパスのディレクトリ

  2. TEMPLATEPATH(現在の親テーマのディレクトリ)
    get_template_directory() で取得するパスのディレクトリ

  3. ABSPATH . WPINC . '/theme-compat/'(/wp-include/theme-compat/ )
    ※ theme-compat は WordPress デフォルトのテーマファイル(header.php や footer.php、sidebar.php など)が入っているディレクトリです。

$load が true の場合は、load_template() でファイルを読み込み、そうでなければパスを含むファイル名を返します。ファイルが見つからない場合は、$located が 「''」なので空文字列を返します。

function locate_template($template_names, $load = false, $require_once = true ) {
  $located = '';
  foreach ( (array) $template_names as $template_name ) {
    if ( !$template_name )
      continue;
    if ( file_exists(STYLESHEETPATH . '/' . $template_name)) {
      $located = STYLESHEETPATH . '/' . $template_name;
      break;
    } elseif ( file_exists(TEMPLATEPATH . '/' . $template_name) ) {
      $located = TEMPLATEPATH . '/' . $template_name;
      break;
    } elseif ( file_exists( ABSPATH . WPINC . '/theme-compat/' . $template_name ) ) {
      $located = ABSPATH . WPINC . '/theme-compat/' . $template_name;
      break;
    }
  }

  if ( $load && '' != $located )
    load_template( $located, $require_once );

  return $located;
}

STYLESHEETPATH などの定数は「wp-include/default-constants.php」に定義されています。

WPINC は「wp-settings.php」で「define( 'WPINC', 'wp-includes' )」のように定義されています。

ABSPATH は WordPress がインストールされている(wp-load.php または wp-config.php が置かれている)ディレクトリのフルパスが入っている定数です。WordPress がインストールされているディレクトリにある wp-load.php wp-config.php で以下のように定義されています。

 // wp-load.php 抜粋 
define( 'ABSPATH', dirname( __FILE__ ) . '/' );
require_once( ABSPATH . 'wp-config.php' );
// wp-config.php 抜粋
if ( !defined('ABSPATH') )
  define('ABSPATH', dirname(__FILE__) . '/');

dirname() は親ディレクトリのパスを返す関数で、 __FILE__ はファイルのフルパスとファイル名を表すマジック定数なので、ABSPATH の値は wp-config.php がインストールされているディレクトリのフルパスになります(最後に「/」が付いています)。

load_template

PHP の require_once() または require() を使って WordPress 環境へテンプレートファイルを読み込みます。また、この関数は PHP の extract() を使ってクエリ変数を、読み込むテンプレートのスコープにインポートします。

load_template( $_template_file, $require_once )

パラメータ
  • $_template_file(文字列):(必須) テンプレートファイルのパス。
  • $require_once(真偽値):(オプション) require_once を使うか require を使うかの指定。 初期値: true(require_once を使う)
戻り値
なし

以下がソースです。

5行目で PHP の extract() を使ってクエリ変数をシンボルテーブル(変数を管理するテーブルでスコープごとに1つのシンボルテーブルがある)にインポートしています。これにより、テンプレートファイルに対してこれらの変数($wp_query->query_vars)がセットアップされ、クエリ変数が使用可能になるようです。

8~10行目は、isset() で検索キーワード($s)がセットされているかを確認して、セットされていればエスケープ処理しています。

12~16行目で第二引数の値により、require_once() または require() を使ってテンプレートファイルを読み込んでいます。

function load_template( $_template_file, $require_once = true ) {
  global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;

  if ( is_array( $wp_query->query_vars ) ) {
    extract( $wp_query->query_vars, EXTR_SKIP );
  }

  if ( isset( $s ) ) {
    $s = esc_attr( $s );
  }

  if ( $require_once ) {
    require_once( $_template_file );
  } else {
    require( $_template_file );
  }
}

以下はテンプレートで「mytemplate.php」と言うファイルを読み込んで、「mytemplate.php」でテンプレートで set_query_var() を使って設定した変数を使えるようにする例です。

※但し、これはこの関数の説明のためのサンプルで、実際のテンプレートパーツの読み込みは、get_template_part() を使うほうが良いかと思います。get_template_part() の内部では load_template() が使われています。

locate_template() を使って「mytemplate.php」がテーマディレクトリに在るかを検索し、ファイルがあれば load_template() で読み込んでいます。

<?php
$template = locate_template('mytemplate.php');

if( $template ){
  set_query_var('my_var', 'Hello My Template!' );
  load_template( $template );
}
?>

mytemplate.php で以下のように get_query_var() で変数の値を取得して echo すると「Hello My Template!」と出力されます。

<?php echo get_query_var('my_var'); ?>

シンボルテーブルについては「変数管理の基礎(PHPの参照とは何か)-PHP変数管理 (2)」に詳しい解説があります。また、「参照カウント法の原理」でも触れられています。

テンプレートで必須の関数

以下の wp_head() と wp_footer() はテーマのテンプレート(header.php や footer.php)に必須の関数です。記述しないとテーマが正常に機能しない可能性が高いです。

テンプレートでよく使われる関数

body_class

<body> タグにページ種類に応じた class 属性を出力する関数です。ページの種類に応じて、body 要素の class 属性にクラスを割り当てたい場合に利用します。

body_class( $class )

パラメータ
$class (string|array) :追加クラス名(オプション)
戻り値
なし
利用可能箇所
どこでも可能

基本的な使い方は、以下のように <body> タグ内に記述します。

<body <?php body_class(); ?>>
          
//以下はメインページでの出力例
<body class="home blog">

出力されるクラス名は、テンプレートの種類やログイン状態などにより異なります。

以下は body_class() で出力される class 属性の例です。 スタイルシートに予めこれらのクラスを定義しておくことで、ページの種類やログイン状態によりスタイルを変更することができます。

どのような class 属性が出力されるかは、get_body_class() のソースで確認することができます。

body_class 関数で出力される class 属性(主な例)
ページの種類 class 属性の値
メインページ home blog
投稿のページ single single-post postid-投稿のID
固定ページ page page-id-固定ページのID page-template page-template-テンプレート名
カテゴリーのアーカイブページ archive category category-カテゴリーのスラッグ
タグのアーカイブページ archive tag tag-タグのスラッグ
日付系のアーカイブページ archive date
ユーザーのアーカイブページ archive author authro-ユーザー名
検索結果のページ search
検索結果がある場合: search-results
検索結果がない場合: search-no-results

ログインしている場合は、以下のような「logged-in」などのクラスが出力されます。

//以下はログイン状態でのメインページでの出力例
<body class="home blog logged-in admin-bar no-customize-support">

例えばログインしている場合のみ表示したい内容があれば、以下のような方法で実現できます。動的に出力されるクラスを利用することで色々と応用できるかも知れません。

<div class="admin_section">
  ログイン時のみ表示する内容
</div>
body .admin_section {
  display: none;
}
body.logged-in .admin_section {
  display: block;
}

追加クラスの指定

オプションの引数($class)を指定すれば、body 要素に独自のクラスを追加することができます。

複数のクラスを追加する場合は、クラス名の間をスペースで区切って指定します。

<body <?php body_class('my-class'); ?>>

//メインページでの出力例(my-class が追加されます)
<body class="home blog my-class">

フィルターフックを使ったクラスの追加

'body_class' フィルターフックを使って、独自のクラスを追加することができます。

追加したいクラスを配列 $classes に追加して返す関数を作成して add_filter() で 'body_class' に登録します。以下は my-class と言うクラスを追加する例です。

add_filter( 'body_class', 'add_my_classes' );
function add_my_classes( $classes ) {
  $classes[] = 'my-class';
  return $classes;
} 

以下のように記述しても上記と同じことになります。

add_filter( 'body_class', 'add_my_classes' );
function add_my_classes( $classes ) {
  return array_merge( $classes, array( 'my-class' ) );
} 

フィルターフックを使うと、特定の条件でクラスを追加することができます。

以下は、カテゴリーが「music」の場合、その一覧ページと個別ページに「music」というクラスを追加する例です。デフォルトでは、body_class() によって一覧ページと個別ページに共通のクラスは出力されません。

add_filter('body_class', 'add_my_classes');
function add_my_classes($classes) {
 if(in_category('music')) {  //カテゴリーが「music」の場合
  $classes[] = 'music';//「music」というクラスを(配列 $classes[] に)追加
 }
 return $classes;
} 

以下は投稿または固定ページの場合にページのスラッグ(パーマリンク)をクラスに追加する例です。

但し、この場合パーマリンク設定で %postname% を使用していて、スラッグは半角英数字で指定してある必要があります。

add_filter( 'body_class', 'add_my_classes' );
function add_my_classes( $classes ) {
  if ( is_page() || is_single() ) {
    $classes[] = get_post( get_the_ID() )->post_name;
  } 
  return $classes;
} 

複数の処理を記述することもできます。$classes[] にクラスを追加して、最後に必ず $classes を return します。以下は公式テーマ「twentynineteen」の template-functions.php の例です。

function twentynineteen_body_classes( $classes ) {

  if ( is_singular() ) {
    // Adds `singular` to singular pages.
    $classes[] = 'singular';
  } else {
    // Adds `hfeed` to non singular pages.
    $classes[] = 'hfeed';
  }

  // Adds a class if image filters are enabled.
  if ( twentynineteen_image_filters_enabled() ) {
    $classes[] = 'image-filters-enabled';
  }
  //最後に必ず return します
  return $classes;
}
add_filter( 'body_class', 'twentynineteen_body_classes' );

クラスの削除

body_class() によって自動的に出力されるクラスを削除したい場合は、フィルターを使って以下のようにすると削除することができます。「class-to-remove」に削除したいクラスの文字列を指定します。

add_filter( 'body_class', function( $classes ) {
  foreach($classes as $key => $class) {
    if( $class == "class-to-remove" ){
      unset($classes[$key]);
    }
  }
  return $classes;
});

前述の例では、無名関数を使用していますが以下のように記述することもできます。

add_filter( 'body_class', 'remove_default_classes');
function remove_default_classes( $classes ) {
  foreach($classes as $key => $class) {
    if( $class == "class-to-remove" ){
      unset($classes[$key]);
    }
  }
  return $classes;
};