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

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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(en:Template Tags/How to Pass Tag Parameters 2008年3月1日 (土) 21:53 Klawdyo 版)
 
(一部和訳+補足説明)
1行目: 1行目:
== Introduction ==  
+
{{NeedTrans}}
 +
{{テーマ・テンプレートガイド}}
 +
<div id="Introduction">
 +
== はじめに ==
 +
</div>
  
[[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 | <code>the_author_firstname()</code>]] は、パラメータのないタグの一つです。このタグは単に記事の著者の姓を表示するだけです。パラメータなしのタグは、関数の括弧内には何も書きません。
  
 
  <?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()]] タグは、2つのパラメータを受け取れます。1つめは '''sep'''(区切り文字)パラメータ、2つめは '''echo'''(表示)パラメータです。(訳注: WordPress 2.5 ではパラメータが 3つとなりました。)
  
%%% <?php wp_title(' - ', TRUE); ?> %%%
+
<?php wp_title(' - ', TRUE); ?>
  
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番目にあるから '''echo''' パラメータであると伝わりますが、1番目に TRUE と書いても、'''sep''' パラメータに TRUE が指定されてしまい、正常に動作しません。
  
Important points to keep in mind for PHP function-style parameters:
+
なお、1つめのパラメータがシングルクオートで囲まれていて、2つめは違うのは、1つめが「文字列」パラメータで、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',
+
テンプレートタグの関数にパラメータを渡すときは、''変更(指定)したい最後(一番右)のパラメータより前にある''全てのパラメータの値を記入してください。でないと、期待通りに動かないかもしれません。例えば、テンプレートタグ <code>[[テンプレートタグ/get_archives|get_archives()]]</code> には 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 />');
+
?>%%%
+
  
 +
<pre><?php get_archives('', '', 'custom', '', '<br />'); ?></pre>
  
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.
+
「空」のパラメータ値を示すシングルクオートを用いると、このケースでは、これらのパラメータに初期値を与えることになります。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 が初期値を使うためです。
  
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(); ?>%%%
+
最後に、テンプレートタグの全パラメータを初期値のまま使うには、パラメータ値の指定なしで次のように書きます。
  
== Tags with query-string-style parameters ==
+
<?php get_archives(); ?>
  
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!
+
<div id="Tags_with_query-string-style_parameters">
 +
== クエリ文字列型パラメータのタグ ==
 +
</div>
  
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:
+
テンプレートタグの最後の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 ものパラメータがあります。
 +
 
 +
<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'); ?>  
105行目: 116行目:
 
  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.
 
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.
  
=== 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()]].  
 
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()]].  
117行目: 132行目:
 
  <?php the_title('\&#39;', '\&#39;'); ?>  
 
  <?php the_title('\&#39;', '\&#39;'); ?>  
  
=== Integer ===
+
<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()]].
 
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()]].
127行目: 144行目:
 
  <?php get_permalink(100); ?>  
 
  <?php get_permalink(100); ?>  
  
=== Boolean ===
+
<div id="Boolean">
 +
=== 真偽値 ===
 +
</div>
  
 
Boolean parameters provide a simple true/false evaluation.  
 
Boolean parameters provide a simple true/false evaluation.  
143行目: 162行目:
 
{{原文|Template Tags/How to Pass Tag Parameters|54159}}
 
{{原文|Template Tags/How to Pass Tag Parameters|54159}}
  
[[Category:Template Tags]]
+
{{DEFAULTSORT:てんふれえとたくはらめえたあのわたしかた}}
[[Category:Advanced Topics]]
+
[[Category:テンプレートタグ]]
 +
[[Category:上級トピック]]
  
 
[[en:Template Tags/How to Pass Tag Parameters]]
 
[[en:Template Tags/How to Pass Tag Parameters]]

2008年4月2日 (水) 23:38時点における版

このページ「テンプレートタグ/タグパラメータの渡し方」は未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています

テンプレートタグとは、動的なブログコンテンツを提供するために 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 />'); ?>

「空」のパラメータ値を示すシングルクオートを用いると、このケースでは、これらのパラメータに初期値を与えることになります。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 for information on parameter types). 第6パラメータは省略していますが、これは、指定されていない残りのパラメータには WordPress が初期値を使うためです。

各テンプレートタグのページをよく読んで、テンプレートタグが期待する順にパラメータを置くようにしてください。

最後に、テンプレートタグの全パラメータを初期値のまま使うには、パラメータ値の指定なしで次のように書きます。

<?php get_archives(); ?>

クエリ文字列型パラメータのタグ

テンプレートタグの最後の1種類は、「クエリ文字列型」と呼ばれるパラメータの渡し方をします。 These provide a convenient 'wrapper' to tags which use the PHP function parameter style and have a relatively large number of parameters. 例えば、wp_list_cats()list_cats() で、18 ものパラメータがあります。

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'); ?> 

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.)

The tag wp_list_authors() has six parameters, of which we set three here:

<?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 (&). Broken down, the tag as shown above states:

  • Parameter show_fullname (a boolean type parameter) equals 1 (true).
AND
  • Parameter feed (a string type parameter) equals rss.
AND
  • Parameter optioncount (a boolean type parameter) equals 1 (true).

(See 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'); ?>

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(
                      'show_fullname=1'
                      .'&feed=rss'
                      .'&optioncount=1'
                      ); ?>

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',
                       'limit'  => 5,
                       'format' => 'custom',
                       'before' => '<li>&bull;&nbsp;',
                       'after'  => '</li>' );
wp_get_archives($params); ?>

パラメータの種類

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.

文字列

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 bloginfo(). Otherwise, a string is intended as text to be displayed, such as the sep parameter in wp_title().

In tags which use the 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: \), as the following does to assign single quotes for the before and after parameters in the_title():

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

整数

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 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 get_permalink().

When passed to a PHP function parameter style tag, integer values either in or out of quotes will be handled correctly. So the following examples are both valid:

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

真偽値

Boolean parameters provide a simple true/false evaluation.

For example, the the_date() tag has an echo parameter which takes either TRUE or FALSE as a value; setting the parameter to TRUE displays the date on the page, whereas FALSE causes the tag to "return" the date as a value that can then be used in other PHP code.

A boolean parameter can be notated as a numeric value: 1 for TRUE, 0 for FALSE. For a boolean value in PHP function parameter style tags, these are all equivalent:

  • 1 = TRUE = true
  • 0 = FALSE = false

However, do NOT enclose boolean values within quote marks. For query-string style tags, use only the numeric boolean values (1 or 0).


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

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