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

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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(11:38, 4 June 2009 Ramiy 版に更新、翻訳完了)
(リンク切れ・誤記を修正)
2行目: 2行目:
 
{{Rename|T}}
 
{{Rename|T}}
 
{{テーマ・テンプレートガイド}}
 
{{テーマ・テンプレートガイド}}
<div id="Introduction">
 
 
== はじめに ==
 
== はじめに ==
</div>
 
  
 
[[テンプレートタグ]]とは、動的なブログコンテンツを提供するために WordPress [[テンプレート]]に埋め込むことができる [[用語集#PHP|PHP]] 関数です。テンプレートタグの多くは、PHP 関数と同様に'''引数(パラメータ)'''を受け付けます。テンプレートタグ引数は、タグが出力する情報を変えたり、何らかの形でその動作を変更したりできる変数です。引数をユーザオプションや設定と考えると、テンプレートタグの動作をカスタマイズできる手段だといえます。
 
[[テンプレートタグ]]とは、動的なブログコンテンツを提供するために WordPress [[テンプレート]]に埋め込むことができる [[用語集#PHP|PHP]] 関数です。テンプレートタグの多くは、PHP 関数と同様に'''引数(パラメータ)'''を受け付けます。テンプレートタグ引数は、タグが出力する情報を変えたり、何らかの形でその動作を変更したりできる変数です。引数をユーザオプションや設定と考えると、テンプレートタグの動作をカスタマイズできる手段だといえます。
10行目: 8行目:
 
引数の指定方法で分けると、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>
24行目: 22行目:
 
  <?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>
55行目: 53行目:
 
アーカイブリストを表示するために、仮に第3引数('''format''')と第5引数('''after''')だけ変更したいとしましょう。このためには、第1・2・4引数にも初期値を与える必要があります。途中を省略したら、引数の位置がずれてしまうからです。
 
アーカイブリストを表示するために、仮に第3引数('''format''')と第5引数('''after''')だけ変更したいとしましょう。このためには、第1・2・4引数にも初期値を与える必要があります。途中を省略したら、引数の位置がずれてしまうからです。
  
<nowiki><?php get_archives('', '', 'custom', '', '<br />'); ?></nowiki>
+
<pre><?php get_archives('', '', 'custom', '', '<br />'); ?></pre>
  
「空」の引数値を示すシングルクォート('')を用いると、これらの引数に初期値を与えることになります。空の引数を渡した場合、初期値が上書きされることもあることに注意しましょう。デフォルトで指定されたテキストが表示されなくなったり、真偽値の場合、空の値は不正になったりといったことがあります。ドキュメンテーションを確認し、初期値が指定されている場合はその値を指定するようにしましょう(また、引数の種類に関する詳しい情報については、[[#Types of parameters|引数の種類]]の項を参照してください)。上記の例では6番目の引数が省略されていますが、これは、指定されていない残りの引数には初期値が使われるためです。
+
「空」の引数値を示すシングルクォート(<code><nowiki>''</nowiki></code>)を用いると、これらの引数に初期値を与えることになります。空の引数を渡した場合、初期値が上書きされることもあることに注意しましょう。デフォルトで指定されたテキストが表示されなくなったり、真偽値の場合、空の値は不正になったりといったことがあります。ドキュメンテーションを確認し、初期値が指定されている場合はその値を指定するようにしましょう(また、引数の種類に関する詳しい情報については、[[#Types of parameters|引数の種類]]の項を参照してください)。上記の例では6番目の引数が省略されていますが、これは、指定されていない残りの引数には初期値が使われるためです。
  
 
各テンプレートタグのページをよく読んで、テンプレートタグが想定している順に引数を書くようにしてください。
 
各テンプレートタグのページをよく読んで、テンプレートタグが想定している順に引数を書くようにしてください。
63行目: 61行目:
 
最後に、テンプレートタグの全引数を初期値のまま使うには、値の指定をせずに次のように書きます。
 
最後に、テンプレートタグの全引数を初期値のまま使うには、値の指定をせずに次のように書きます。
  
<nowiki><?php get_archives(); ?></nowiki>
+
<?php get_archives(); ?>
  
<div id="Tags_with_query-string-style_Parameters">
+
<div id="Tags_with_query-string-style_parameters">
 
== クエリ文字列型引数のタグ ==
 
== クエリ文字列型引数のタグ ==
 
</div>
 
</div>
  
テンプレートタグの最後の1種類は、「クエリ文字列型」と呼ばれる引数の渡し方をします。これらのタグには便利なラッパーというものがあり、[[#Tags with PHP function-style Parameters|PHP 関数引数のスタイル]]を使った比較的数の多い引数を持っています。例えば、[[Template_Tags/wp_list_cats|wp_list_cats()]] は18個もの引数がある [[Template_Tags/list_cats|list_cats()]] のラッパーです。
+
テンプレートタグの最後の1種類は、「クエリ文字列型」と呼ばれる引数の渡し方をします。これらのタグには便利なラッパーというものがあり、[[#Tags with PHP function-style parameters|PHP 関数引数のスタイル]]を使った比較的数の多い引数を持っています。例えば、[[テンプレートタグ/wp_list_cats|wp_list_cats()]] は18個もの引数がある [[テンプレートタグ/list_cats|list_cats()]] のラッパーです。
  
 
<code>list_cats()</code> の場合、'''exclude''' 引数(17番目の引数)を指定してその他は初期値のままとしたいときは、次のように書かなければなりません。
 
<code>list_cats()</code> の場合、'''exclude''' 引数(17番目の引数)を指定してその他は初期値のままとしたいときは、次のように書かなければなりません。
82行目: 80行目:
 
クエリ文字列型タグは、すべての引数を指定することなく、必要な引数だけを変更できるので便利です。しかし、すべての PHP 関数型テンプレートタグにクエリ文字列型タグが用意されているわけではありません(クエリ文字列型タグは、例えば wp_list_cats() のように 'wp_' 接頭詞で始まることが多いですが、詳しくはタグのドキュメンテーションを確認してください)。
 
クエリ文字列型タグは、すべての引数を指定することなく、必要な引数だけを変更できるので便利です。しかし、すべての PHP 関数型テンプレートタグにクエリ文字列型タグが用意されているわけではありません(クエリ文字列型タグは、例えば wp_list_cats() のように 'wp_' 接頭詞で始まることが多いですが、詳しくはタグのドキュメンテーションを確認してください)。
  
[[Template Tags/wp_list_authors|wp_list_authors()]] タグには6つの引数がありますが、以下の例ではそのうち3つを指定しています。
+
[[テンプレートタグ/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'); ?>
115行目: 113行目:
 
  wp_get_archives($params); ?>
 
  wp_get_archives($params); ?>
  
<div id="Types_of_Parameters">
+
<div id="Types_of_parameters">
 
== 引数の種類 ==
 
== 引数の種類 ==
 
</div>
 
</div>
125行目: 123行目:
 
</div>
 
</div>
  
文字列とはテキストのことです。この場合の引数は、例えば、[[Template Tags/bloginfo|bloginfo()]] タグの '''show''' 引数のような用意された選択肢のうちのひとつか、または、[[Template Tags/wp_title|wp_title()]] タグの '''sep''' 引数のような表示テキストになります。
+
文字列とはテキストのことです。この場合の引数は、例えば、[[テンプレートタグ/bloginfo|bloginfo()]] タグの '''show''' 引数のような用意された選択肢のうちのひとつか、または、[[テンプレートタグ/wp_title|wp_title()]] タグの '''sep''' 引数のような表示テキストになります。
  
[[#Tags with PHP function-style Parameters|PHP 関数型引数]]を使うタグでは、文字列の値はシングル(')またはダブル(")クォートの間に記入しなくてはなりません。シングル/ダブルクォートが文字列に含まれている場合は、開始・終了の囲みクォートと文字列の値内にあるクォートに別のものを使うか、PHP エスケープ記号(バックスラッシュ: <tt>\</tt>)をクォートの前に記入します。下記は [[Template Tags/the_title|the_title()] タグの '''before''' と '''after''' 引数の例です。
+
[[#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;'); ?>  
135行目: 133行目:
 
</div>
 
</div>
  
整数は(…, -2, -1, 0, 1, 2,…)のような小数点を持たない数です。整数引数は [[Template Tags/get_month_link|get_month_link()]] タグの ''year''' や '''month''' 引数のような日付やアーカイブに関する情報や、[[関数リファレンス/get_permalink|get_permalink()]] の '''id''' 因数のようなブログ内の数値を指定するときなどによく使われます。
+
整数は(…, -2, -1, 0, 1, 2,…)のような小数点を持たない数です。整数引数は [[テンプレートタグ/get_month_link|get_month_link()]] タグの ''year''' や '''month''' 引数のような日付やアーカイブに関する情報や、[[テンプレートタグ/get_permalink|get_permalink()]] の '''id''' 因数のようなブログ内の数値を指定するときなどによく使われます。
  
[[#Tags with PHP function-style Parameters|PHP 関数型引数]]タグに渡す場合、整数値はクォートで禍根でも囲まなくても正しく処理されます。例えば、以下はどちらも正しい書き方です。
+
[[#Tags with PHP function-style parameters|PHP 関数型引数]]タグに渡す場合、整数値はクォートで禍根でも囲まなくても正しく処理されます。例えば、以下はどちらも正しい書き方です。
  
 
  <?php get_permalink('100'); ?>  
 
  <?php get_permalink('100'); ?>  
149行目: 147行目:
 
真偽値は、単純な真偽の判定に使います。
 
真偽値は、単純な真偽の判定に使います。
  
例えば、[[Template_Tags/the_date|the_date()]] タグに <tt>TRUE</tt> または <tt>FALSE</tt> を値とする '''echo''' 引数 があるとします。引数を <tt>TRUE</tt> に設定すると、日付をページに出力し、<tt>FALSE</tt> にすると、PHP で利用できる値として日付を返すのみとなります。
+
例えば、[[テンプレートタグ/the_date|the_date()]] タグに <tt>TRUE</tt> または <tt>FALSE</tt> を値とする '''echo''' 引数 があるとします。引数を <tt>TRUE</tt> に設定すると、日付をページに出力し、<tt>FALSE</tt> にすると、PHP で利用できる値として日付を返すのみとなります。
  
真偽値の引数は数字でも指定できます。その場合<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>0</tt>は <tt>FALSE</tt>です。[[#Tags with PHP function-style parameters|PHP 関数型引数]]を持つタグでは、以下のいずれの真偽値も使う事ができます。
  
 
:* <tt>1</tt> = <tt>TRUE</tt> = <tt>真</tt>  
 
:* <tt>1</tt> = <tt>TRUE</tt> = <tt>真</tt>  
 
:* <tt>0</tt> = <tt>FALSE</tt> = <tt>偽</tt>
 
:* <tt>0</tt> = <tt>FALSE</tt> = <tt>偽</tt>
  
ただし、真偽値はクォートで'''囲まない'''ようにしてください。For [[#Tags with query-string-style Parameters|クエリ文字列型タグ]]の場合は、数字の真偽値(<tt>1</tt>または<tt>0</tt>)のみを使ってください。
+
ただし、真偽値はクォートで'''囲まない'''ようにしてください。[[#Tags with query-string-style parameters|クエリ文字列型タグ]]の場合は、数字の真偽値(<tt>1</tt>または<tt>0</tt>)のみを使ってください。
  
{{Tag Footer}}
+
{{No Param Tag Footer}}
 
{{原文|Template Tags/How to Pass Tag Parameters|73376}}
 
{{原文|Template Tags/How to Pass Tag Parameters|73376}}
  
 
{{DEFAULTSORT:てんふれえとたくはらめえたあのわたしかた}}
 
{{DEFAULTSORT:てんふれえとたくはらめえたあのわたしかた}}
[[Category:テンプレートタグ]]
+
[[Category:テンプレートタグ|はらめえたあのわたしかた]]
 
[[Category:上級トピック]]
 
[[Category:上級トピック]]
  
 
[[en:Template Tags/How to Pass Tag Parameters]]
 
[[en:Template Tags/How to Pass Tag Parameters]]

2010年1月10日 (日) 11:46時点における版

この項目「テンプレートタグ/タグパラメータの渡し方」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、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 エスケープ記号(バックスラッシュ: \)をクォートの前に記入します。下記は 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)のみを使ってください。


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

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