• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

テンプレートタグ/タグパラメータの渡し方

提供: WordPress Codex 日本語版
移動先: 案内検索

この項目「テンプレートタグ/タグパラメータの渡し方」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

はじめに

テンプレートタグとは、動的なブログコンテンツを提供するために WordPress テンプレートに埋め込むことができる PHP 関数です。テンプレートタグの多くは、PHP 関数と同様に引数(パラメータ)を受け付けます。テンプレートタグ引数は、タグが出力する情報を変えたり、何らかの形でその動作を変更したりできる変数です。引数をユーザオプションや設定と考えると、テンプレートタグの動作をカスタマイズできる手段だといえます。

引数の指定方法で分けると、WordPress テンプレートタグは次の3種類の形式があります。以下、それぞれについて説明します。

  1. 引数なしのタグ
  2. PHP 関数型引数のタグ
  3. クエリ文字列型引数のタグ

引数なしのタグ

テンプレートタグの中には、何もオプションがなく、渡せる引数のないものがあります。

テンプレートタグ the_author_firstname() は、引数のないタグの一つです。このタグは投稿の作成者の姓を単に表示します。引数なしのタグは、関数の括弧内には何も書きません。

<?php the_author_firstname(); ?>

PHP 関数型引数のタグ

引数が使えるテンプレートタグには、PHP の書式で引数を指定するものがあります。このタイプのタグ関数に引数を渡すには、関数の括弧内に一つ以上の値を書きます。

bloginfo() タグは、ブログについての何の情報を表示するかを指定する引数(show 引数)を一つだけ受け取ります。

<?php bloginfo( 'name' ); ?>

wp_title() タグは、3つまでの引数を受け取ります。1つめは sep(区切り文字)引数、2つめは display(表示)引数です。3つめの seplocation(区切り文字の位置)引数は、sep 文字列をサイトのタイトルの前(左側)と後(右側)のどちらにつけるかを示します。サイトのタイトルは 設定 > 一般設定 で設定されます。

<?php wp_title( ' - ', TRUE, 'right' ); ?> 

PHP 関数型テンプレートタグの関数に引数を渡すときは、指定されているとおりの順番で引数を記述しなければなりません。括弧内の「何番目に書かれているか」によって、何についての指定値であるか判断されるのです。この例でいうと、TRUE は 2番目にあるから display 引数であると伝わりますが、1番目に TRUE と書いても、sep 引数に TRUE が指定されてしまい、正常に動作しません。

1つめと3つめの引数がシングルクォートで囲まれていて、2つめは違うのは、1つめと3つめが「文字列」引数で、2つめは「真偽値」引数だからです。(引数の種類と扱い方については引数の種類を参照。)

PHP 関数型引数の重要な点は、

  • 関数によっては引数が複数ある
  • 複数の引数間はカンマ(,)で区切る
  • 引数の順序が重要!

テンプレートタグの関数に引数を渡すときは、変更(指定)したい最後(一番右)の引数より前にあるすべての引数の値を記入してください。そうしないと、期待通りに動かないかもしれません。例えば、テンプレートタグ get_archives() には6つの引数があります。

<?php get_archives( 'type', 'limit', 'format', 'before', 'after', show_post_count ); ?>

アーカイブリストを表示するために、仮に第3引数(format)と第5引数(after)だけ変更したいとしましょう。このためには、第1・2・4引数にも初期値を与える必要があります。途中を省略したら、引数の位置がずれてしまうからです。

<?php get_archives( '', '', 'custom', '', '<br />' ); ?>

「空」の引数値を示すシングルクォート('')を用いると、これらの引数に初期値を与えることになります。空の引数を渡した場合、初期値が上書きされることもあることに注意しましょう。デフォルトで指定されたテキストが表示されなくなったり、真偽値の場合、空の値は不正になったりといったことがあります。ドキュメンテーションを確認し、初期値が指定されている場合はその値を指定するようにしましょう(また、引数の種類に関する詳しい情報については、引数の種類の項を参照してください)。上記の例では6番目の引数が省略されていますが、これは、指定されていない残りの引数には初期値が使われるためです。

各テンプレートタグのページをよく読んで、テンプレートタグが想定している順に引数を書くようにしてください。最後に、テンプレートタグの全引数を初期値のまま使うには、値の指定をせずに次のように書きます。

<?php get_archives(); ?>

クエリ文字列型引数のタグ

テンプレートタグの最後の1種類は、「クエリ文字列型」と呼ばれる引数の渡し方をします。これらのタグは、PHP 関数引数のスタイルを使った比較的数の多い引数を持つタグに対する、便利なラッパーの役割を持ちます。例えば、wp_list_cats() は18個もの引数がある list_cats() のラッパーです。

list_cats() の場合、exclude 引数(17番目の引数)を指定してその他は初期値のままとしたいときは、次のように書かなければなりません。

<?php list_cats( TRUE, 'All', 'ID', 'asc', '', TRUE, FALSE, FALSE, 
TRUE, TRUE, FALSE, '', '', FALSE, '', '', '10,11,12' ); ?> 

wp_list_cats() であれば次のように使えます。

<?php wp_list_cats( 'exclude=10,11,12' ); ?> 

クエリ文字列型タグは、すべての引数を指定することなく、必要な引数だけを変更できるので便利です。しかし、すべての PHP 関数型テンプレートタグにクエリ文字列型タグが用意されているわけではありません(クエリ文字列型タグは、例えば wp_list_cats() のように 'wp_' 接頭詞で始まることが多いですが、詳しくはタグのドキュメンテーションを確認してください)。

wp_list_authors() タグには6つの引数がありますが、以下の例ではそのうち3つを指定しています。

<?php wp_list_authors( 'show_fullname=1&feed=rss&optioncount=1' ); ?>

まず、すべての引数をシングルまたはダブルクォートで囲みます。それから、各引数を 引数=値 という形式で入力し、それぞれをアンド記号(&)でつないでいきます。上記のタグを詳しく見てみると以下のようになります。

  • 引数 show_fullname真偽値型引数)の値は1(真)
そして
  • 引数 feed文字列型引数)の値は rss.
そして
  • 引数 optioncount真偽値型引数)の値は1(真)

(引数の種類と使い方に関する詳しい情報については 引数の種類 の項を参照してください。)

クエリ文字列型の引数は、特定の順序で記入する必要はありません。ただ、引数名が間違っていないことに注意しましょう。読みにくいようであれば、引数をスペースで区切ってください。

<?php wp_list_authors( 'show_fullname=1 & feed=rss & optioncount=1' ); ?>

クエリ文字列を複数の行にわたって書くこともできます(引数/値の各ペアをシングルクォートで囲み、新しい行の先頭にドットを置きます)。

<?php wp_list_authors(
                      'show_fullname=1'
                      .'&feed=rss'
                      .'&optioncount=1'
                      ); ?>

クエリ文字列型のタグを使うときには使えない文字があります。アンパサンド(半角&記号)やシングル・ダブルクォーテーションマークなどです。こういった文字を使うときには、連想配列を使う必要があります。

<?php $params = array( 'type'   => 'postbypost',
                       'limit'  => 5,
                       'format' => 'custom',
                       'before' => '<li>&bull;&nbsp;',
                       'after'  => '</li>' );
wp_get_archives( $params ); ?>

引数の種類

WordPress テンプレートタグで使う引数には、文字列、整数、真偽値の3種類があります。以下のように少しずつ取り扱い方が異なります。

文字列

文字列とはテキストのことです。この場合の引数は、例えば、bloginfo() タグの show 引数のような用意された選択肢のうちのひとつか、または、wp_title() タグの sep 引数のような表示テキストになります。

PHP 関数型引数を使うタグでは、文字列の値はシングル(')またはダブル(")クォートの間に記入しなくてはなりません。シングル/ダブルクォートが文字列に含まれている場合は、開始・終了の囲みクォートと文字列の値内にあるクォートに別のものを使うか、PHP エスケープ記号(バックスラッシュ: \)をクォートの前に記入します。下記は the_title() タグの beforeafter 引数の例です。

<?php the_title( '\'', '\'' ); ?> 

整数

整数は(…, -2, -1, 0, 1, 2,…)のような小数点を持たない数です。整数引数は get_month_link() タグの year'month 引数のような日付やアーカイブに関する情報や、get_permalink()id 引数のようなブログ内の数値を指定するときなどによく使われます。

PHP 関数型引数タグに渡す場合、整数値はクォートで禍根でも囲まなくても正しく処理されます。例えば、以下はどちらも正しい書き方です。

<?php get_permalink( '100' ); ?> 
<?php get_permalink( 100 ); ?>

真偽値

真偽値は、単純な真偽の判定に使います。

例えば、the_date() タグに TRUE または FALSE を値とする echo 引数があります。引数を TRUE にすると日付をページに出力し、FALSE にすると PHP で利用できる値として日付を返すのみとなります。

真偽値の引数は数字でも指定できます。その場合1TRUE0FALSEです。PHP 関数型引数を持つタグでは、以下のいずれの真偽値も使う事ができます。

  • 1 = TRUE =
  • 0 = FALSE =

ただし、真偽値はクォートで囲まないようにしてください。クエリ文字列型タグの場合は、数字の真偽値(1または0)のみを使ってください。

コールバック

特殊な引数としてコールバック(PHP 5.4 では callable ともいう)があります。これは文字列または配列で、関数名への参照か、クラス/オブジェクト内のメソッドへの参照です。以下にコールバック関数の基本的な例を示します:

 add_action( 'wp_head', 'myfuncprefix_add_meta_tag' ); // 文字列で関数名を指定
 function myfuncprefix_add_meta_tag() {
   echo '<meta name="description" content="This is an example meta tag" />';
 }

クラス/オブジェクト内のメソッド参照は、オブジェクトの内外どちらでも行うことができます。このときパラメータは要素2つの配列で、1つめをオブジェクト、2つめをメソッド(文字列)とします。いくつか例を示します:

 class Myclassprefix_Some_Class {
   function __construct(){
     add_action( 'wp_head', array( $this, 'myfuncprefix_add_meta_tag' ) );
   }
   function myfuncprefix_add_meta_tag() {
     echo '<meta name="description" content="This is an example meta tag" />';
   }
 }

これをクラスの外側で行う例は:

 class Myclassprefix_Some_Class {
   function myfuncprefix_add_meta_tag() {
     echo '<meta name="description" content="This is an example meta tag" />';
   }
 }
 
 $some_class = new Myclassprefix_Some_Class;
 
 add_action( 'wp_head', array( $some_class, 'myfuncprefix_add_meta_tag' ) );

参考: コールバックに余分な配列要素を渡してはいけません。2つの要素しか受け取らないだけでなく、余分な要素があるとコールバックが動作しません。

関連項目

関数リファレンステンプレートタグ目次もご覧ください。


最新英語版: WordPress Codex » How to Pass Tag Parameters最新版との差分