Web Design Leaves

テンプレートタグが定義されている場所

テンプレートタグの定義は、WordPress をインストールしたディレクトリ内の wp-includes フォルダ内に ***-template.php というファイルに記述されています（*** はテンプレートタグの分類）。

テンプレートタグの調べ方

以下はテンプレートタグを調べるのに便利なサイトです。それぞれのサイトには右上に検索ボックスがあるので、調べたい関数（テンプレートタグ）やフィルタ名などを入力して検索することができます。

• WordPress Codex（日本語）：テンプレートタグ
• WordPress Codex（日本語）：テンプレートタグ入門
• WordPress Codex（日本語）：関数リファレンス
• WordPress Developer Resources（英語）/Theme Handbook：Template Tags
• WordPress Developer Resources（英語）：Code Reference
• WordPress Developer Resources（英語）：ファイル一覧（バージョンを展開して、src をクリック）
• PHP Cross Reference of WordPress（英語）/Function List (alphabetical)

非推奨のタグ

テンプレートタグの中には、「非推奨」となっているタグがあります。

「非推奨（Deprecated）」というのは「以前は使用されていたが、現在はより良いテンプレートタグがあるのでそちらを使用してください」と言うような意味ですが、将来的には非推奨のタグは廃止になる可能性もあるので、なるべく非推奨のタグは使わないようにします。

非推奨の例として、良く使われる bloginfo() では以下のパラメータの使用は非推奨となっています。（この場合、タグ自体ではなく使用するパラメータが非推奨）

廃止された関数は「wp-includes/deprecated.php (5.0.3)」に記載されています（ * Deprecated functions from past WordPress versions. 以下）。但し、これを毎回確認するのは大変なので、作成したテーマに非推奨のテンプレートタグが使われていないかを調べるには、Theme Check プラグインを使用するのが便利です。Theme Check プラグインは、テーマで使用されている非推奨のテンプレートタグなどをチェックしてくれます。

個々のテンプレートタグの詳しい説明は以下の公式リファレンスに記載されています。

• WordPress Codex（日本語）： bloginfo
  非推奨のパラメータには「xxxx を用いることを推奨します」と記載されています。

• WordPress Code Reference（英語）： bloginfo
  非推奨のパラメータには「Deprecated since version 2.2.」や「Consider echoing xxxx instead.」と記載されています。

テンプレートタグの引数

テンプレートタグの引数（パラメータ）の指定方法には、引数を順番に並べる方法と、１つの引数で複数のパラメータ（パラメータを格納した配列）を指定する方法があります。

WordPress Codex（日本語）：テンプレートタグ/タグパラメータの渡し方

引数を順番に並べて指定する例

ページのタイトルを出力する the_title() は引数を順番に並べて指定するテンプレートタグです。以下が書式とパラメータ（引数）です。

<?php the_title( $before, $after, $echo ); ?>  

the_title() は、以下のように引数をカンマ区切りで順番に並べて値を指定します。

the_title('<h1>', '</h1>', true);

上記の場合、3番目の引数はデフォルトと同じ値なので、以下のように省略しても同じことになります。

the_title('<h1>', '</h1>');

引数を全て省略した場合は、デフォルト値が使われます。

the_title();
//以下を指定したのと同じ
the_title('', '', true);

但し、例えば1番目と2番目はデフォルトの引数を使い、3番目はデフォルト以外を指定する場合、1番目と2番目の引数は省略できず、以下のように記述しなければなりません。

the_title('', '', false);

１つの引数で複数のパラメータを指定する方法

WordPress の引数の多いテンプレートタグや関数では、１つの引数に複数のパラメータを指定するようになっています。

例えば、各種アーカイブリストを出力するテンプレートタグ wp_get_archives() の書式と引数は以下のようになっています。

<?php wp_get_archives( $args ); ?>

クエリ文字列型引数

以下のように指定すると、アーカイブリストを年別（type）で10件（limit）表示します。指定したパラメータ以外はデフォルト値が使われます。

wp_get_archives('type=yearly&limit=10')

クエリ文字列型タグは、引数全体をシングルまたはダブルクォートで囲みます。そして、各引数を「キー = 値」という形式で入力し、それぞれをアンド記号（&）でつないでいきます。

クエリ文字列型タグは、すべての引数を指定することなく、必要な引数だけを変更（指定）することができます。また、クエリ文字列型の引数は、特定の順序で記述する必要はありません。

※クエリ文字列型のタグを使うときには、アンパサンドやシングル・ダブルクォーテーションなど使えない文字があります。こういった文字を使うときには、配列型引数を使う必要があります。

配列型引数

以下は、PHP の連想配列を利用した配列型引数を使った指定の例です。以下のように改行して記述できるため、パラメータが多い場合は見やすくなります。

wp_get_archives(array(
　　'type'=>'yearly',
　　'limit'=>10,)); 

配列型引数も、すべての引数を指定することなく、必要な引数だけを変更（指定）することができます。また、クエリ文字列型の引数は、特定の順序で記述する必要はありません。

また、配列型引数の場合、以下のように引数を任意の変数としてテンプレートタグと別に記述しておくこともできます。

$myArgs = array(
  'type' => 'yearly',
  'limit' => 10);
wp_get_archives($myArgs); 

引数の順番指定と複数のパラメータ指定が混在するテンプレートタグ

register_post_type() などは、順番指定と複数のパラメータを指定するタイプのテンプレートタグです。以下が書式です。

<?php register_post_type( $post_type, $args ); ?>

• $post_type（文字列） 投稿タイプ （必須）
• $args（配列）引数の配列。※詳細は省略

以下が指定例です。

register_post_type(
  'topics',　//$post_type
  array(
    'label' => 'トピックス',　
    'labels' => array(　
      'add_new_item' => '新規トピックスを追加',
      'add_new' => '新規追加',
      'edit_item' => 'トピックスの編集',
      'view_item' => 'トピックスを表示',
      'search_items' => 'トピックスを検索',
      'not_found' => 'トピックスは見つかりませんでした。',
      'not_found_in_trash' => 'ゴミ箱にトピックスはありませんでした。',
    ),
    'public' => true,
    'hierarchicla' => false,　
    'has_archive' => true,
    'supports' => array(　
      'title',
      'editor',
      'thumbnail',
      'excerpt'　
    ),
    'menu_position' => 5　　
  )
);

独自（代替）テンプレートタグ

functions.php に PHP の関数を定義することで、テンプレートタグと同様にその関数をテーマから呼び出すことができます。

例えば、月別アーカイブページの月・年名を表示するテンプレートタグ single_month_title() は、日本語環境で出力すると「5月2018」のようになってしまいます。

テンプレートタグ single_month_title() は、wp-include/general-template.php に以下のように定義されています。

function single_month_title($prefix = '', $display = true ) {
  global $wp_locale;

  $m = get_query_var('m');
  $year = get_query_var('year');
  $monthnum = get_query_var('monthnum');

  if ( !empty($monthnum) && !empty($year) ) {
    $my_year = $year;
    $my_month = $wp_locale->get_month($monthnum);
  } elseif ( !empty($m) ) {
    $my_year = substr($m, 0, 4);
    $my_month = $wp_locale->get_month(substr($m, 4, 2));
  }

  if ( empty($my_month) )
    return false;

  $result = $prefix . $my_month . $prefix . $my_year;

  if ( !$display )
    return $result;
  echo $result;
}    

get_query_var() を使って年月の値を取得して、月の値を $wp_locale から言語設定に応じた値に変更して変数 $result に代入して出力または値を返すようになっています。

以下は上記関数の一部を変更して「2018年5月」のように出力または値を返す関数 single_month_title_jp() を functions.php に記述して定義する例です。

function single_month_title_jp($prefix = '', $display = true ) {
  global $wp_locale;

  $m = get_query_var('m');
  $year = get_query_var('year');
  $monthnum = get_query_var('monthnum');

  if ( !empty($monthnum) && !empty($year) ) {
    $my_year = $year;
    $my_month = $wp_locale->get_month($monthnum);
  } elseif ( !empty($m) ) {
    $my_year = substr($m, 0, 4);
    $my_month = $wp_locale->get_month(substr($m, 4, 2));
  }

  if ( empty($my_month) )
    return false;

  //$result = $prefix . $my_month . $prefix . $my_year; ※この行を以下に書き換えただけ
  $result = $my_year .'年' .$prefix .$my_month ;

  if ( !$display )
    return $result;
  echo $result;
}    

以下のように定義してもほぼ同じ結果になります。

function single_month_title_jp($prefix = '', $display = true ) {
  $year = get_query_var('year');
  $monthnum = get_query_var('monthnum');
  $result = $year .'年' .$prefix .$monthnum .'月';

  if ( !$display )
    return $result;
  echo $result;
}

コロン(:)を使った構文

テンプレートの記述を見ると、<?php if (have_posts()) : ?> ～ <?php endif; ?> のようにコロン(:)を使って波括弧 { } を使わない記述がありますが、これは PHP の制御構造の別の構文で、Web ページに記述する（HTML に埋め込む）際に使用すると便利です。

この構文は、if, switch, while, for, foreach の制御構造で使用することができます。

参考：PHP マニュアル「制御構造に関する別の構文」

例えば、通常の if 文の場合、以下のような記述になります。

<?php
$x = 3;
if($x >= 5) {
  echo '$x は5以上です。';
}else{
  echo '$x は5未満です。';
} 
?>

上記をコロン(:)を使った構文に書き換えると以下のようになります。最後の閉じ括弧の代わりに endif; を記述しています。

<?php
$x = 3;
if($x >= 5) :
  echo '$x は5以上です。';
else:
  echo '$x は5未満です。';
endif; 
?>

以下は、Web ページに記述する（HTML に埋め込む）場合の例です。波括弧を使って記述するよりスッキリと記述できます。

<?php if ($username == 'Suzuki'): ?>
<p>Suzuki さん、こんにちは</p>
<?php elseif ($username == 'Tanaka'): ?>
<p>Tanaka さん、こんにちは</p>
<?php else: ?>
<p>名無しさん、こんにちは</p>
<?php endif; ?>

echo とテンプレートタグ

テンプレートタグには、bloginfo() のように値をブラウザに出力（表示）するものと、get_the_title() のように値を返すだけのものがあります。

the_ で始まるテンプレートタグ

the_ID や the_title といった「the_」を前置するテンプレートタグは、echo を行っているテンプレートタグでブラウザに出力されます。

get_ で始まるテンプレートタグ

get_the_ID や get_the_title など「get_」を前置するテンプレートタグは、echo を行わず値を返すテンプレートタグです。ブラウザに出力するには echo が必要です。出力する際には、必要に応じてエスケープ処理をします。

また、引数の指定により echo を行うか、値を返すかの選択のできるテンプレートタグもあります。例えば、the_title の display 引数に false を指定すると echo はされず値としてタイトルが返ってきます。但し、全てのタグがこのような規則になっているわけではないので、タグごとに確認する必要があります。

<a href="<?php echo get_permalink();?>">link</a>

function the_permalink( $post = 0 ) {
    /**
    * Filters the display of the permalink for the current post.
    *
    * @since 1.5.0
    * @since 4.4.0 Added the `$post` parameter.
    *
    * @param string      $permalink The permalink for the current post.
    * @param int|WP_Post $post      Post ID, WP_Post object, or 0. Default 0.
    */
  echo esc_url( apply_filters( 'the_permalink', get_permalink( $post ), $post ) );
}

$permalink_value = esc_url( apply_filters( 'the_permalink', get_permalink() ) );