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

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

「テンプレートタグ/タグパラメータの渡し方」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(2 版)
(11:38, 4 June 2009 Ramiy 版に更新、翻訳完了)
1行目: 1行目:
{{NeedTrans}}
+
{{CheckTrans}}
 +
{{Rename|T}}
 
{{テーマ・テンプレートガイド}}
 
{{テーマ・テンプレートガイド}}
 
<div id="Introduction">
 
<div id="Introduction">
5行目: 6行目:
 
</div>  
 
</div>  
  
[[テンプレートタグ]]とは、動的なブログコンテンツを提供するために WordPress [[テンプレート]]に埋め込むことができる [[用語集#PHP|PHP]] 関数です。テンプレートタグの多くは、PHP 関数と同様に'''引数(パラメータ)'''を受け付けます。テンプレートタグパラメータは、タグが出力する情報を変えたり、何らかの形でその動作を変更したりできる変数です。パラメータをユーザオプションや設定と考えると、テンプレートタグの動作をカスタマイズできる手段だといえます。
+
[[テンプレートタグ]]とは、動的なブログコンテンツを提供するために WordPress [[テンプレート]]に埋め込むことができる [[用語集#PHP|PHP]] 関数です。テンプレートタグの多くは、PHP 関数と同様に'''引数(パラメータ)'''を受け付けます。テンプレートタグ引数は、タグが出力する情報を変えたり、何らかの形でその動作を変更したりできる変数です。引数をユーザオプションや設定と考えると、テンプレートタグの動作をカスタマイズできる手段だといえます。
  
パラメータの指定方法で分けると、WordPress テンプレートタグは次の 3種類の形式があります。以下、それぞれについて説明します。
+
引数の指定方法で分けると、WordPress テンプレートタグは次の 3種類の形式があります。以下、それぞれについて説明します。
  
# [[#Tags without parameters|パラメータなしのタグ]]
+
# [[#Tags without Parameters|引数なしのタグ]]
# [[#Tags with PHP function-style parameters|PHP 関数型パラメータのタグ]]
+
# [[#Tags with PHP function-style Parameters|PHP 関数型引数のタグ]]
# [[#Tags with query-string-style parameters|クエリ文字列型パラメータのタグ]]
+
# [[#Tags with query-string-style Parameters|クエリ文字列型引数のタグ]]
  
<div id="Tags_without_parameters">
+
<div id="Tags_without_Parameters">
== パラメータなしのタグ ==
+
== 引数なしのタグ ==
 
</div>
 
</div>
  
テンプレートタグの中には、何もオプションがなく、渡せるパラメータのないものがあります。
+
テンプレートタグの中には、何もオプションがなく、渡せる引数のないものがあります。
  
テンプレートタグ [[テンプレートタグ/the_author_firstname | <code>the_author_firstname()</code>]] は、パラメータのないタグの一つです。このタグは単に記事の著者の姓を表示するだけです。パラメータなしのタグは、関数の括弧内には何も書きません。
+
テンプレートタグ [[テンプレートタグ/the_author_firstname | <code>the_author_firstname()</code>]] は、引数のないタグの一つです。このタグは単に記事の著者の姓を表示するだけです。引数なしのタグは、関数の括弧内には何も書きません。
  
 
  <?php the_author_firstname(); ?>
 
  <?php the_author_firstname(); ?>
  
<div id="Tags_with_PHP_function-style_parameters">
+
<div id="Tags_with_PHP_function-style_Parameters">
== PHP 関数型パラメータのタグ ==
+
== PHP 関数型引数のタグ ==
 
</div>
 
</div>
  
パラメータが使えるテンプレートタグには、[http://jp.php.net/manual/ja/functions.arguments.php PHP の書式]でパラメータを指定するものがあります。このタイプのタグ関数にパラメータを渡すには、関数の括弧内に一つ以上の値を書きます。
+
引数が使えるテンプレートタグには、[http://jp.php.net/manual/ja/functions.arguments.php PHP の書式]で引数を指定するものがあります。このタイプのタグ関数に引数を渡すには、関数の括弧内に一つ以上の値を書きます。
  
[[テンプレートタグ/bloginfo|bloginfo()]] タグは、ブログについての何の情報を表示するかを指定するパラメータ(''show'' パラメータ)を一つだけ受け取れます。
+
[[テンプレートタグ/bloginfo|bloginfo()]] タグは、ブログについての何の情報を表示するかを指定する引数(''show'' 引数)を一つだけ受け取れます。
  
 
  <?php bloginfo('name'); ?>
 
  <?php bloginfo('name'); ?>
  
[[テンプレートタグ/wp_title|wp_title()]] タグは、2つのパラメータを受け取れます。1つめは '''sep'''(区切り文字)パラメータ、2つめは '''echo'''(表示)パラメータです。(訳注: WordPress 2.5 ではパラメータが 3つとなりました。)
+
[[テンプレートタグ/wp_title|wp_title()]] タグは、2つの引数を受け取れます。1つめは '''sep'''(区切り文字)引数、2つめは '''echo'''(表示)引数です。(訳注: WordPress 2.5 では引数が 3つとなりました。)
  
 
  <?php wp_title(' - ', TRUE); ?>
 
  <?php wp_title(' - ', TRUE); ?>
  
PHP 関数型テンプレートタグの関数にパラメータを渡すときは、指定されているとおりの順番でパラメータを記述しなければなりません。括弧内の「何番目に書かれているか」によって、何についての指定値であるか判断されるのです。この例でいうと、TRUE は 2番目にあるから '''echo''' パラメータであると伝わりますが、1番目に TRUE と書いても、'''sep''' パラメータに TRUE が指定されてしまい、正常に動作しません。
+
PHP 関数型テンプレートタグの関数に引数を渡すときは、指定されているとおりの順番で引数を記述しなければなりません。括弧内の「何番目に書かれているか」によって、何についての指定値であるか判断されるのです。この例でいうと、TRUE は 2番目にあるから '''echo''' 引数であると伝わりますが、1番目に TRUE と書いても、'''sep''' 引数に TRUE が指定されてしまい、正常に動作しません。
  
なお、1つめのパラメータがシングルクオートで囲まれていて、2つめは違うのは、1つめが「文字列」パラメータで、2つめは「真偽値」パラメータだからです。(パラメータの種類と扱い方については[[#Types of parameters|パラメータの種類]]を参照)
+
なお、1つめの引数がシングルクォートで囲まれていて、2つめは違うのは、1つめが「文字列」引数で、2つめは「真偽値」引数だからです。(引数の種類と扱い方については[[#Types of parameters|引数の種類]]を参照)
  
PHP 関数型パラメータの重要な点は、
+
PHP 関数型引数の重要な点は、
  
:* 関数によってはパラメータが複数ある
+
:* 関数によっては引数が複数ある
:* 複数のパラメータ間はカンマ(,)で区切る
+
:* 複数の引数間はカンマ(,)で区切る
:* '''パラメータの順序が重要!'''  
+
:* '''引数の順序が重要!'''  
  
テンプレートタグの関数にパラメータを渡すときは、''変更(指定)したい最後(一番右)のパラメータより前にある''全てのパラメータの値を記入してください。でないと、期待通りに動かないかもしれません。例えば、テンプレートタグ <code>[[テンプレートタグ/get_archives|get_archives()]]</code> には 6つのパラメータがあります。
+
テンプレートタグの関数に引数を渡すときは、''変更(指定)したい最後(一番右)の引数より前にある''全ての引数の値を記入してください。でないと、期待通りに動かないかもしれません。例えば、テンプレートタグ <code>[[テンプレートタグ/get_archives|get_archives()]]</code> には 6つの引数があります。
  
 
  <?php get_archives('type', 'limit', 'format', 'before',  
 
  <?php get_archives('type', 'limit', 'format', 'before',  
 
                   'after', show_post_count); ?>
 
                   'after', show_post_count); ?>
  
アーカイブリストを表示するために、仮に第3パラメータ('''format''')と第5パラメータ('''after''')だけ変更したいとしましょう。このためには、第1・2・4パラメータにも初期値を与える必要があります。途中を省略したら、パラメータの位置がずれてしまうからです。
+
アーカイブリストを表示するために、仮に第3引数('''format''')と第5引数('''after''')だけ変更したいとしましょう。このためには、第1・2・4引数にも初期値を与える必要があります。途中を省略したら、引数の位置がずれてしまうからです。
  
<pre><?php get_archives('', '', 'custom', '', '<br />'); ?></pre>
+
<nowiki><?php get_archives('', '', 'custom', '', '<br />'); ?></nowiki>
  
「空」のパラメータ値を示すシングルクオートを用いると、このケースでは、これらのパラメータに初期値を与えることになります。Be aware that defaults can be overwritten when passing empty parameters, as is the case of a parameter specifying a string of text, and there's no way to pass an empty boolean value. So check the documentation for a parameter's default, and when one is specified use it as your parameter value (also see [[#Types of parameters|Types of parameters]] for information on parameter types). 第6パラメータは省略していますが、これは、指定されていない残りのパラメータには WordPress が初期値を使うためです。
+
「空」の引数値を示すシングルクォート('')を用いると、これらの引数に初期値を与えることになります。空の引数を渡した場合、初期値が上書きされることもあることに注意しましょう。デフォルトで指定されたテキストが表示されなくなったり、真偽値の場合、空の値は不正になったりといったことがあります。ドキュメンテーションを確認し、初期値が指定されている場合はその値を指定するようにしましょう(また、引数の種類に関する詳しい情報については、[[#Types of parameters|引数の種類]]の項を参照してください)。上記の例では6番目の引数が省略されていますが、これは、指定されていない残りの引数には初期値が使われるためです。
  
各テンプレートタグのページをよく読んで、テンプレートタグが期待する順にパラメータを置くようにしてください。
+
各テンプレートタグのページをよく読んで、テンプレートタグが想定している順に引数を書くようにしてください。
  
最後に、テンプレートタグの全パラメータを初期値のまま使うには、パラメータ値の指定なしで次のように書きます。
+
最後に、テンプレートタグの全引数を初期値のまま使うには、値の指定をせずに次のように書きます。
  
<?php get_archives(); ?>
+
<nowiki><?php get_archives(); ?></nowiki>
  
<div id="Tags_with_query-string-style_parameters">
+
<div id="Tags_with_query-string-style_Parameters">
== クエリ文字列型パラメータのタグ ==
+
== クエリ文字列型引数のタグ ==
 
</div>
 
</div>
  
テンプレートタグの最後の1種類は、「クエリ文字列型」と呼ばれるパラメータの渡し方をします。 These provide a convenient 'wrapper' to tags which use the [[#Tags with PHP function-style parameters|PHP function parameter style]] and have a relatively large number of parameters. 例えば、[[Template_Tags/wp_list_cats|wp_list_cats()]] [[Template_Tags/list_cats|list_cats()]] で、18 ものパラメータがあります。
+
テンプレートタグの最後の1種類は、「クエリ文字列型」と呼ばれる引数の渡し方をします。これらのタグには便利なラッパーというものがあり、[[#Tags with PHP function-style Parameters|PHP 関数引数のスタイル]]を使った比較的数の多い引数を持っています。例えば、[[Template_Tags/wp_list_cats|wp_list_cats()]] は18個もの引数がある [[Template_Tags/list_cats|list_cats()]] のラッパーです。
  
<code>list_cats()</code> の場合、'''exclude''' パラメータ(17番目のパラメータ)を指定してその他は初期値のままとしたいときは、次のように書かなければなりません。
+
<code>list_cats()</code> の場合、'''exclude''' 引数(17番目の引数)を指定してその他は初期値のままとしたいときは、次のように書かなければなりません。
  
 
  <?php list_cats(TRUE, 'All', 'ID', 'asc', &#39;&#39;, TRUE, FALSE, FALSE,  
 
  <?php list_cats(TRUE, 'All', 'ID', 'asc', &#39;&#39;, TRUE, FALSE, FALSE,  
79行目: 80行目:
 
  <?php wp_list_cats('exclude=10,11,12'); ?>  
 
  <?php wp_list_cats('exclude=10,11,12'); ?>  
  
So query-string style tags are useful in that they let you change the values of just those parameters you require, without needing to provide values for all or nearly all of them. However, not all PHP function-style template tags have a query-string style equivalent. (Also note that names for tags that accept query-string style parameters usually start with a 'wp_' prefix, such as wp_list_cats(), but check the documentation on a tag to verify its method for accepting parameters, if any.)
+
クエリ文字列型タグは、すべての引数を指定することなく、必要な引数だけを変更できるので便利です。しかし、すべての PHP 関数型テンプレートタグにクエリ文字列型タグが用意されているわけではありません(クエリ文字列型タグは、例えば wp_list_cats() のように 'wp_' 接頭詞で始まることが多いですが、詳しくはタグのドキュメンテーションを確認してください)。
  
The tag [[Template Tags/wp_list_authors|wp_list_authors()]] has six parameters, of which we set three here:
+
[[Template Tags/wp_list_authors|wp_list_authors()]] タグには6つの引数がありますが、以下の例ではそのうち3つを指定しています。
  
 
  <?php wp_list_authors('show_fullname=1&feed=rss&optioncount=1'); ?>
 
  <?php wp_list_authors('show_fullname=1&feed=rss&optioncount=1'); ?>
  
First, all the parameters together are enclosed by either single or double quotes. Then each parameter is entered in the ''parameter=value'' format, while these are separated with an ampersand (&amp;). Broken down, the tag as shown above states:
+
まず、すべての引数をシングルまたはダブルクォートで囲みます。それから、各引数を ''引数=''という形式で入力し、それぞれをアンド記号(&amp;)でつないでいきます。上記のタグを詳しく見てみると以下のようになります。
  
:* Parameter '''show_fullname''' (a ''boolean'' type parameter) equals <tt>1</tt> (true).
+
:* 引数 '''show_fullname'''''真偽値''型引数)の値は<tt>1</tt>(真)
:: AND
+
:: そして
:* Parameter '''feed''' (a ''string'' type parameter) equals <tt>rss</tt>.
+
:* 引数 '''feed'''''文字列''型引数)の値は <tt>rss</tt>.
:: AND
+
:: そして
:* Parameter '''optioncount''' (a ''boolean'' type parameter) equals <tt>1</tt> (true).
+
:* 引数 '''optioncount'''''真偽値''型引数)の値は<tt>1</tt>(真)
  
(See [[#Types of parameters|Types of parameters]] for information on parameter types and how to use them.)
+
クエリ文字列型の引数は、特定の順序で記入する必要はありません。ただ、引数名が間違っていないことに注意しましょう。読みにくいようであれば、引数をスペースで区切ってください。
 
+
Parameters in the query-string style do not have to be entered in a specific order. The only real concern is assuring parameter names are spelled correctly. If legibility is a problem, you can separate parameters with a space:
+
  
 
  <?php wp_list_authors('show_fullname=1 & feed=rss & optioncount=1'); ?>
 
  <?php wp_list_authors('show_fullname=1 & feed=rss & optioncount=1'); ?>
  
You can also spread a query-string over several lines (note the specific format of enclosing each parameter/value pair in single quotes and a dot starting each new line):
+
クエリ文字列を複数の行にわたって書くこともできます。
  
 
  <?php wp_list_authors(
 
  <?php wp_list_authors(
107行目: 106行目:
 
                       ); ?>
 
                       ); ?>
  
There are a few limitations when using query-string style tags, among which you cannot pass certain characters, such as the ampersand or a quote mark (single or double). In those cases, you can use an associative array:
+
クエリ文字列型のタグを使うときには使えない文字があります。アンパサンド(半角&記号)やシングル・ダブルクォーテーションマークなどです。こういった文字を使うときには、連想配列を使う必要があります。
  
 
  <?php $params = array( 'type'  => 'postbypost',
 
  <?php $params = array( 'type'  => 'postbypost',
116行目: 115行目:
 
  wp_get_archives($params); ?>
 
  wp_get_archives($params); ?>
  
<div id="Types_of_parameters">
+
<div id="Types_of_Parameters">
== パラメータの種類 ==
+
== 引数の種類 ==
 
</div>
 
</div>
  
There are three types of parameters you need to know about in regards to WordPress template tags: string, integer, and boolean. Each is handled a bit differently, as described below.
+
引数には以下の3種類があります。
  
 
<div id="String">
 
<div id="String">
126行目: 125行目:
 
</div>
 
</div>
  
A string is a line of text, and is typically anything from a single character to several dozen words. A string parameter is often a selection from two or more valid options, as is the '''show''' parameter in [[Template Tags/bloginfo|bloginfo()]]. Otherwise, a string is intended as text to be displayed, such as the '''sep''' parameter in [[Template Tags/wp_title|wp_title()]].
+
文字列とはテキストのことです。この場合の引数は、例えば、[[Template Tags/bloginfo|bloginfo()]] タグの '''show''' 引数のような用意された選択肢のうちのひとつか、または、[[Template Tags/wp_title|wp_title()]] タグの '''sep''' 引数のような表示テキストになります。
  
In tags which use the [[#Tags with PHP function-style parameters|PHP function parameter style]], string values should be enclosed in single (') or double (") quotation marks. If a single or double quote is required for part of your string, mix the marks (using double quotes to enclose the parameter if a single quote exists in your parameter value), or use the PHP escape character (a backslash: <tt>\</tt>), as the following does to assign single quotes for the '''before''' and '''after''' parameters in [[Template Tags/the_title|the_title()]]:
+
[[#Tags with PHP function-style Parameters|PHP 関数型引数]]を使うタグでは、文字列の値はシングル(')またはダブル(")クォートの間に記入しなくてはなりません。シングル/ダブルクォートが文字列に含まれている場合は、開始・終了の囲みクォートと文字列の値内にあるクォートに別のものを使うか、PHP エスケープ記号(バックスラッシュ: <tt>\</tt>)をクォートの前に記入します。下記は [[Template Tags/the_title|the_title()] タグの '''before''' '''after''' 引数の例です。
  
 
  <?php the_title('\&#39;', '\&#39;'); ?>  
 
  <?php the_title('\&#39;', '\&#39;'); ?>  
136行目: 135行目:
 
</div>
 
</div>
  
An integer is a whole number, and can have a positive (1, 2, 3) or negative (-1, -2, -3) value. Integer parameters are often used for date and archive based information, like the '''year''' and '''month''' parameters for the [[Template Tags/get_month_link|get_month_link()]] tag, or for specifying the numeric value of something on your blog, as one finds in the case of the '''id''' parameter in [[Template_Tags/get_permalink|get_permalink()]].
+
整数は(…, -2, -1, 0, 1, 2,…)のような小数点を持たない数です。整数引数は [[Template Tags/get_month_link|get_month_link()]] タグの ''year''' '''month''' 引数のような日付やアーカイブに関する情報や、[[関数リファレンス/get_permalink|get_permalink()]] '''id''' 因数のようなブログ内の数値を指定するときなどによく使われます。
  
When passed to a [[#Tags with PHP function-style parameters|PHP function parameter style]] tag, integer values either in or out of quotes will be handled correctly. So the following examples are both valid:
+
[[#Tags with PHP function-style Parameters|PHP 関数型引数]]タグに渡す場合、整数値はクォートで禍根でも囲まなくても正しく処理されます。例えば、以下はどちらも正しい書き方です。
  
 
  <?php get_permalink('100'); ?>  
 
  <?php get_permalink('100'); ?>  
  
  <?php get_permalink(100); ?>  
+
  <?php get_permalink(100); ?>
  
 
<div id="Boolean">
 
<div id="Boolean">
148行目: 147行目:
 
</div>
 
</div>
  
Boolean parameters provide a simple true/false evaluation.
+
真偽値は、単純な真偽の判定に使います。
  
For example, the [[Template_Tags/the_date|the_date()]] tag has an '''echo''' parameter which takes either <tt>TRUE</tt> or <tt>FALSE</tt> as a value; setting the parameter to <tt>TRUE</tt> displays the date on the page, whereas <tt>FALSE</tt> causes the tag to "return" the date as a value that can then be used in other PHP code.
+
例えば、[[Template_Tags/the_date|the_date()]] タグに <tt>TRUE</tt> または <tt>FALSE</tt> を値とする '''echo''' 引数 があるとします。引数を <tt>TRUE</tt> に設定すると、日付をページに出力し、<tt>FALSE</tt> にすると、PHP で利用できる値として日付を返すのみとなります。
  
A boolean parameter can be notated as a numeric value: <tt>1</tt> for <tt>TRUE</tt>, <tt>0</tt> for <tt>FALSE</tt>. For a boolean value in [[#Tags with PHP function-style parameters|PHP function parameter style]] tags, these are all equivalent:
+
真偽値の引数は数字でも指定できます。その場合<tt>1</tt><tt>TRUE</tt><tt>0</tt><tt>FALSE</tt>です。[[#Tags with PHP function-style Parameters|PHP 関数型引数]]を持つタグでは、以下のいずれの真偽値も使う事ができます。
  
:* <tt>1</tt> = <tt>TRUE</tt> = <tt>true</tt>  
+
:* <tt>1</tt> = <tt>TRUE</tt> = <tt></tt>  
:* <tt>0</tt> = <tt>FALSE</tt> = <tt>false</tt>
+
:* <tt>0</tt> = <tt>FALSE</tt> = <tt></tt>
  
However, do '''NOT''' enclose boolean values within quote marks. For [[#Tags with query-string-style parameters|query-string style tags]], use only the numeric boolean values (<tt>1</tt> or <tt>0</tt>).
+
ただし、真偽値はクォートで'''囲まない'''ようにしてください。For [[#Tags with query-string-style Parameters|クエリ文字列型タグ]]の場合は、数字の真偽値(<tt>1</tt>または<tt>0</tt>)のみを使ってください。
  
{{No Param Tag Footer}}
+
{{Tag Footer}}
{{原文|Template Tags/How to Pass Tag Parameters|54159}}
+
{{原文|Template Tags/How to Pass Tag Parameters|73376}}
  
 
{{DEFAULTSORT:てんふれえとたくはらめえたあのわたしかた}}
 
{{DEFAULTSORT:てんふれえとたくはらめえたあのわたしかた}}

2009年7月10日 (金) 21:02時点における版

この項目「テンプレートタグ/タグパラメータの渡し方」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、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() タグは、2つの引数を受け取れます。1つめは sep(区切り文字)引数、2つめは echo(表示)引数です。(訳注: WordPress 2.5 では引数が 3つとなりました。)

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

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

なお、1つめの引数がシングルクォートで囲まれていて、2つめは違うのは、1つめが「文字列」引数で、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); ?>

引数の種類

引数には以下の3種類があります。

文字列

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

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

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


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

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