当サイト、Codex 日本語版は今後積極的な更新は行わない予定です。後継となる新ユーザーマニュアルは、https://ja.wordpress.org/support/ にあります。
万が一、当サイトで重大な問題を発見した際などは、フォーラムWordSlack #docs チャンネルでお知らせください。</p>

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(en:Template Tags/How to Pass Tag Parameters 2008年3月1日 (土) 21:53 Klawdyo 版)
 
(残りを和訳。)
 
(3人の利用者による、間の6版が非表示)
1行目: 1行目:
== Introduction ==  
+
{{CheckTrans}}
 +
{{テーマ・テンプレートガイド}}
 +
== はじめに ==
  
[[Template Tags|Template tags]] are [[Glossary#PHP|PHP]] functions you can embed in your WordPress page templates to provide dynamic blog content. And like PHP functions, many template tags accept arguments, or parameters. Template tag parameters are variables you can use to change a tag's output or otherwise modify its action in some way. Think of parameters as user options or settings that allow you to customize how a template tag works.
+
[[テンプレートタグ]]とは、動的なブログコンテンツを提供するために WordPress [[テンプレート]]に埋め込むことができる [[用語集#PHP|PHP]] 関数です。テンプレートタグの多くは、PHP 関数と同様に'''引数(パラメータ)'''を受け付けます。テンプレートタグ引数は、タグが出力する情報を変えたり、何らかの形でその動作を変更したりできる変数です。引数をユーザオプションや設定と考えると、テンプレートタグの動作をカスタマイズできる手段だといえます。
  
In regards to parameters, WordPress template tags come in three "flavors." These are described below:
+
引数の指定方法で分けると、WordPress テンプレートタグは次の3種類の形式があります。以下、それぞれについて説明します。
  
# [[#Tags without parameters|Tags without parameters]]
+
# [[#Tags without parameters|引数なしのタグ]]
# [[#Tags with PHP function-style parameters|Tags with PHP function-style parameters]]
+
# [[#Tags with PHP function-style parameters|PHP 関数型引数のタグ]]
# [[#Tags with query-string-style parameters|Tags with query-string-style parameters]]
+
# [[#Tags with query-string-style parameters|クエリ文字列型引数のタグ]]
  
== Tags without parameters ==
+
<div id="Tags_without_parameters">
 +
== 引数なしのタグ ==
 +
</div>
  
Some template tags do not have any options, and thus have no parameters you can pass to them.
+
テンプレートタグの中には、何もオプションがなく、渡せる引数のないものがあります。
  
The template tag [[Template_Tags/the_author_firstname | the_author_firstname()]] is one that accepts no parameters. This tag simply displays the first name of the author for a post. Tags without parameters should have nothing between the tag function's opening and closing brackets (parentheses):
+
テンプレートタグ [[テンプレートタグ/the_author_firstname | the_author_firstname()]] は、引数のないタグの一つです。このタグは投稿の作成者の姓を単に表示します。引数なしのタグは、関数の括弧内には何も書きません。
  
 
  <?php the_author_firstname(); ?>
 
  <?php the_author_firstname(); ?>
  
== Tags with PHP function-style parameters ==
+
<div id="Tags_with_PHP_function-style_parameters">
 +
== PHP 関数型引数のタグ ==
 +
</div>
  
For template tags that can accept parameters, some require them to be in the [http://www.php.net/manual/en/functions.arguments.php default PHP style]. For these, parameters are passed to a tag function by placing one or more values inside the function's parentheses, or brackets.
+
引数が使えるテンプレートタグには、[http://jp.php.net/manual/ja/functions.arguments.php PHP の書式]で引数を指定するものがあります。このタイプのタグ関数に引数を渡すには、関数の括弧内に一つ以上の値を書きます。
  
The [[Template Tags/bloginfo|bloginfo()]] tag accepts one parameter (known as the '''show''' parameter) that tells it what information about your blog to display:
+
[[テンプレートタグ/bloginfo|bloginfo()]] タグは、ブログについての何の情報を表示するかを指定する引数(''show'' 引数)を一つだけ受け取ります。
  
%%% <?php bloginfo('name'); ?>%%%
+
<?php bloginfo( 'name' ); ?>
  
The [[Template Tags/wp_title|wp_title()]] tag accepts two parameters: the first is the '''sep''' or separator parameter, and the second the '''echo''' or display parameter:
+
[[テンプレートタグ/wp_title|wp_title()]] タグは、3つまでの引数を受け取ります。1つめは '''sep'''(区切り文字)引数、2つめは '''display'''(表示)引数です。3つめの '''seplocation'''(区切り文字の位置)引数は、sep 文字列をサイトのタイトルの前(左側)と後(右側)のどちらにつけるかを示します。サイトのタイトルは [[管理画面#Settings|設定]] > [[管理画面#General|一般設定]] で設定されます。
  
%%% <?php wp_title(' - ', TRUE); ?> %%%
+
<?php wp_title( ' - ', TRUE, 'right' ); ?>  
  
The first is enclosed in single-quotes and the second is not because the first is a ''string'', and the second a ''boolean'' parameter. (See [[#Types of parameters|Types of parameters]] for information on parameter types and how to use them.)
+
PHP 関数型テンプレートタグの関数に引数を渡すときは、指定されているとおりの順番で引数を記述しなければなりません。括弧内の「何番目に書かれているか」によって、何についての指定値であるか判断されるのです。この例でいうと、TRUE は 2番目にあるから '''display''' 引数であると伝わりますが、1番目に TRUE と書いても、'''sep''' 引数に TRUE が指定されてしまい、正常に動作しません。
  
Important points to keep in mind for PHP function-style parameters:
+
1つめと3つめの引数がシングルクォートで囲まれていて、2つめは違うのは、1つめと3つめが「文字列」引数で、2つめは「真偽値」引数だからです。(引数の種類と扱い方については[[#Types of parameters|引数の種類]]を参照。)
  
:* Some functions take multiple parameters. 
+
PHP 関数型引数の重要な点は、
:* Multiple parameters are separated by commas. 
+
:* '''The order of parameters is important!'''
+
  
When passing parameters to a template tag's function, make sure you specify values for all parameters ''up to the last one you wish to modify'', or the tag may not work as expected. For example, the template tag [[Template Tags/get_archives|get_archives()]] has six parameters:
+
:* 関数によっては引数が複数ある
 +
:* 複数の引数間はカンマ(,)で区切る
 +
:* '''引数の順序が重要!'''  
  
%%% <?php get_archives('type', 'limit', 'format', 'before',
+
テンプレートタグの関数に引数を渡すときは、''変更(指定)したい最後(一番右)の引数より前にある''すべての引数の値を記入してください。そうしないと、期待通りに動かないかもしれません。例えば、テンプレートタグ [[テンプレートタグ/get_archives|get_archives()]] には6つの引数があります。
                  'after', show_post_count); ?>  %%%
+
  
To display the archives list the way you want, let's say you only need to modify the third ('''format''') and fifth ('''after''') parameters. To do this, you also need to make sure to enter default values for the first, second and fourth parameters, as well:
+
<?php get_archives( 'type', 'limit', 'format', 'before', 'after', show_post_count ); ?>
  
%%%<?php get_archives(
+
アーカイブリストを表示するために、仮に第3引数('''format''')と第5引数('''after''')だけ変更したいとしましょう。このためには、第1・2・4引数にも初期値を与える必要があります。途中を省略したら、引数の位置がずれてしまうからです。
'', '', 'custom', '', '<br />');
+
?>%%%
+
  
 +
<nowiki><?php get_archives( '', '', 'custom', '', '<br />' ); ?></nowiki>
  
Notice the use of single-quotes to denote ''empty'' parameter values, which ''in this case'' forces defaults for those specific parameters. 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). The sixth parameter was left off; this is because WordPress uses the default for any remaining parameters left unspecified.
+
「空」の引数値を示すシングルクォート(<code><nowiki>''</nowiki></code>)を用いると、これらの引数に初期値を与えることになります。空の引数を渡した場合、初期値が上書きされることもあることに注意しましょう。デフォルトで指定されたテキストが表示されなくなったり、真偽値の場合、空の値は不正になったりといったことがあります。ドキュメンテーションを確認し、初期値が指定されている場合はその値を指定するようにしましょう(また、引数の種類に関する詳しい情報については、[[#Types of parameters|引数の種類]]の項を参照してください)。上記の例では6番目の引数が省略されていますが、これは、指定されていない残りの引数には初期値が使われるためです。
  
Make sure to follow the documentation for a template tag carefully, and place your parameters in the order the template function expects. Finally, to use the defaults for all parameters in a template tag, use the tag with no parameter values specified:
+
各テンプレートタグのページをよく読んで、テンプレートタグが想定している順に引数を書くようにしてください。最後に、テンプレートタグの全引数を初期値のまま使うには、値の指定をせずに次のように書きます。
  
  %%%<?php get_archives(); ?>%%%
+
  <?php get_archives(); ?>
  
== Tags with query-string-style parameters ==
+
<div id="Tags_with_query-string-style_parameters">
 +
== クエリ文字列型引数のタグ ==
 +
</div>
  
The last type of template tag makes use of what's called a query-string style to pass parameters to the tag. 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. For example, the template tag [[Template_Tags/wp_list_cats|wp_list_cats()]] is a wrapper to [[Template_Tags/list_cats|list_cats()]], a tag with eighteen parameters!
+
テンプレートタグの最後の1種類は、「クエリ文字列型」と呼ばれる引数の渡し方をします。これらのタグは、[[#Tags with PHP function-style parameters|PHP 関数引数のスタイル]]を使った比較的数の多い引数を持つタグに対する、便利なラッパーの役割を持ちます。例えば、[[テンプレートタグ/wp_list_cats|wp_list_cats()]] は18個もの引数がある [[テンプレートタグ/list_cats|list_cats()]] のラッパーです。
  
If you want to set the '''exclude''' parameter in list_cats() (seventeenth in the parameter list) and leave the rest at their defaults, you have to do this:
+
<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,  
  TRUE, TRUE, FALSE, &#39;&#39;, &#39;&#39;, FALSE, &#39;&#39;, &#39;&#39;, '10,11,12'); ?>  
+
  TRUE, TRUE, FALSE, &#39;&#39;, &#39;&#39;, FALSE, &#39;&#39;, &#39;&#39;, '10,11,12' ); ?>  
  
''Or'' you can use wp_list_cats():
+
<code>wp_list_cats()</code> であれば次のように使えます。
  
  <?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:
+
[[テンプレートタグ/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.)
+
(引数の種類と使い方に関する詳しい情報については [[#Types of parameters|引数の種類]] の項を参照してください。)
  
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(
96行目: 102行目:
 
                       ); ?>
 
                       ); ?>
  
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',
103行目: 109行目:
 
                         &#39;before' => '&lt;li&gt;&amp;bull;&amp;nbsp;',
 
                         &#39;before' => '&lt;li&gt;&amp;bull;&amp;nbsp;',
 
                         &#39;after'  => '&lt;/li&gt;' );
 
                         &#39;after'  => '&lt;/li&gt;' );
  wp_get_archives($params); ?>
+
  wp_get_archives( $params ); ?>
  
== Types of parameters ==
+
<div id="Types_of_parameters">
 +
== 引数の種類 ==
 +
</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.
+
WordPress テンプレートタグで使う引数には、文字列、整数、真偽値の3種類があります。以下のように少しずつ取り扱い方が異なります。
  
=== String ===
+
<div id="String">
 +
=== 文字列 ===
 +
</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()]].
+
文字列とはテキストのことです。この場合の引数は、例えば、[[テンプレートタグ/bloginfo|bloginfo()]] タグの '''show''' 引数のような用意された選択肢のうちのひとつか、または、[[テンプレートタグ/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>)をクォートの前に記入します。下記は [[テンプレートタグ/the_title|the_title()]] タグの '''before''' '''after''' 引数の例です。
  
  <?php the_title('\&#39;', '\&#39;'); ?>  
+
  <?php the_title( '\&#39;', '\&#39;' ); ?>  
  
=== Integer ===
+
<div id="Int"><!-- Don't remove this! --></div>
 +
<div id="Integer">
 +
=== 整数 ===
 +
</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,…)のような小数点を持たない数です。整数引数は [[テンプレートタグ/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 ); ?>
  
=== Boolean ===
+
<div id="Bool"><!-- Don't remove this! --></div>
 +
<div id="Boolean">
 +
=== 真偽値 ===
 +
</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.
+
例えば、[[テンプレートタグ/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>).
+
ただし、真偽値はクォートで'''囲まない'''ようにしてください。[[#Tags with query-string-style parameters|クエリ文字列型タグ]]の場合は、数字の真偽値(<tt>1</tt>または<tt>0</tt>)のみを使ってください。
 +
 
 +
<div id="Callable"><!-- Don't remove this! --></div>
 +
=== コールバック ===
 +
 
 +
特殊な引数としてコールバック([http://www.php.net/manual/en/language.types.callable.php 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つの要素しか受け取らないだけでなく、余分な要素があるとコールバックが動作しません。
 +
 
 +
== 関連項目 ==
  
 
{{No Param Tag Footer}}
 
{{No Param Tag Footer}}
{{原文|Template Tags/How to Pass Tag Parameters|54159}}
 
  
[[Category:Template Tags]]
+
{{原文|How to Pass Tag Parameters|145018}} <!-- 20:01, 23 July 2014 Jdgrimes 版 -->
[[Category:Advanced Topics]]
+
 
 +
{{DEFAULTSORT:てんふれえとたくはらめえたあのわたしかた}}
 +
[[Category:テンプレートタグ|はらめえたあのわたしかた]]
 +
[[Category:上級トピック]]
  
 
[[en:Template Tags/How to Pass Tag Parameters]]
 
[[en:Template Tags/How to Pass Tag Parameters]]
 +
[[it:Come passare i parametri]]

2016年4月20日 (水) 00:36時点における最新版

この項目「テンプレートタグ/タグパラメータの渡し方」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、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最新版との差分