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

「テンプレートタグ/wp dropdown categories」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(en:Function Reference/wp_dropdown_categories 07:08, 10 July 2014 Ore4444 版を反映した上で、和訳を改訂。)
(引数: 誤記訂正。箇条書きを使って見やすさ改善。)
72行目: 72行目:
 
</div>
 
</div>
  
{{Parameter|show_option_all|文字列|クリックすると '<tt>すべてのカテゴリー</tt>' を選択できるテキスト。デフォルトでは、'<tt>すべてのカテゴリー</tt>を選択できるテキストを表示しない。|オプション|&#39;&#39;}}
+
{{Parameter|show_option_all|文字列|クリックすると '<tt>すべてのカテゴリー</tt>' を選択できるテキスト。デフォルトでは、'<tt>すべてのカテゴリー</tt>' を選択できるテキストを表示しない。|オプション|&#39;&#39;}}
  
{{Parameter|show_option_none|文字列|クリックすると '<tt>カテゴリーなし</tt>' を指定できるテキスト。デフォルトでは、'<tt>カテゴリーなし</tt>を指定できるテキストを表示しない。|オプション|&#39;&#39;}}
+
{{Parameter|show_option_none|文字列|クリックすると '<tt>カテゴリーなし</tt>' を指定できるテキスト。デフォルトでは、'<tt>カテゴリーなし</tt>' を指定できるテキストを表示しない。|オプション|&#39;&#39;}}
  
{{Parameter|orderby|文字列|カテゴリーをソートするためのキー項目。有効な値は 'ID', 'NAME'(名前), および 'SLUG'(スラッグ)|オプション|'ID'}}
+
{{Parameter|orderby|文字列|カテゴリーをソートするためのキー項目。有効な値は:<ul><li>'ID'</li><li>'NAME'(名前)</li><li>'SLUG'(スラッグ)</li></ul>|オプション|'ID'}}
  
{{Parameter|order|文字列|カテゴリーをソートする方向。有効な値は '<tt>ASC</tt>'(昇順)と '<tt>DESC</tt>'(降順)|オプション|'ASC'}}
+
{{Parameter|order|文字列|カテゴリーをソートする方向。有効な値は:<ul><li>'<tt>ASC</tt>'(昇順)</li><li>'<tt>DESC</tt>'(降順)</li></ul>|オプション|'ASC'}}
  
 
{{Parameter|show_count|真偽値|各カテゴリーに属する投稿数を表示する (1/True) または、しない (0/False)|オプション|0/False}}
 
{{Parameter|show_count|真偽値|各カテゴリーに属する投稿数を表示する (1/True) または、しない (0/False)|オプション|0/False}}
86行目: 86行目:
 
{{Parameter|child_of|整数|カテゴリーを ID で指定して、その子孫のすべてのカテゴリー(子、孫、ひ孫・・・)を表示する。[[関数リファレンス/get_categories|<tt>get_categories()</tt>]] を参照。|オプション|0}}
 
{{Parameter|child_of|整数|カテゴリーを ID で指定して、その子孫のすべてのカテゴリー(子、孫、ひ孫・・・)を表示する。[[関数リファレンス/get_categories|<tt>get_categories()</tt>]] を参照。|オプション|0}}
  
{{Parameter|exclude|文字列|除外したいカテゴリー ID をカンマ区切りで指定。例えば 'exclude=4,12' とすれば、ID が 4 と 12 のカテゴリーを表示しない、または値として返さない。[[Function_Reference/get_categories|<tt>get_categories()</tt>]] を参照。|オプション|&#39;&#39;}}
+
{{Parameter|exclude|文字列|除外したいカテゴリー ID をカンマ区切りで指定。|オプション|&#39;&#39;}}
  
{{Parameter|exclude_tree|文字列|カンマ区切りのリストで、除外したい親カテゴリーの ID を定義する。ある親カテゴリーとその子カテゴリーすべてを除外したい時に使う。例えば '<tt>exclude_tree=5</tt>' を指定すると、ID が 5 のカテゴリーとその子(すべての子孫)カテゴリーが除外される。<tt>hierarchical</tt> 引数が true の場合は、<tt>exclude</tt> 引数の値を使って exclude_tree と同じ処理が実行される。|オプション}}
+
'''参考''':例えば 'exclude=4,12' とすれば、ID が 4 と 12 のカテゴリーを表示しない、または値として返さない。
 +
[[関数リファレンス/get_categories|<tt>get_categories()</tt>]] を参照。
 +
 
 +
{{Parameter|exclude_tree|文字列|カンマ区切りのリストで、除外したい親カテゴリーの ID を定義する。ある親カテゴリーとその子カテゴリーすべてを除外したい時に使う。<tt>hierarchical</tt> 引数が true の場合は、<tt>exclude</tt> 引数の値を使って exclude_tree と同じ処理が実行される。|オプション|&#39;&#39;}}
 +
 
 +
'''参考''':例えば '<tt>exclude_tree=5</tt>' を指定すると、ID が 5 のカテゴリーとその子(すべての子孫)カテゴリーが除外される。
  
 
{{Parameter|echo|真偽値|カテゴリーリストを表示する (1/True) または、PHP で使うために値を返す (0/False)|オプション|1/True}}
 
{{Parameter|echo|真偽値|カテゴリーリストを表示する (1/True) または、PHP で使うために値を返す (0/False)|オプション|1/True}}
94行目: 99行目:
 
{{Parameter|depth|整数|カテゴリー階層のどのレベルまでを出力するかを指定。<tt>hierarchical</tt> 引数が true でなければ、これは無視される。|オプション|0}}
 
{{Parameter|depth|整数|カテゴリー階層のどのレベルまでを出力するかを指定。<tt>hierarchical</tt> 引数が true でなければ、これは無視される。|オプション|0}}
  
'''参考'''
+
'''参考''':depth
 
:* 0 - 全ての階層のカテゴリーを出力
 
:* 0 - 全ての階層のカテゴリーを出力
 
:* -1 - 全てのカテゴリーをフラット(インデントなし)形式で出力(hierarchical 引数よりも優先)
 
:* -1 - 全てのカテゴリーをフラット(インデントなし)形式で出力(hierarchical 引数よりも優先)
100行目: 105行目:
 
:* 2以上 - 指定した階層までを出力。例えば 2 を指定すると、最上位と直下の子カテゴリまでを出力。
 
:* 2以上 - 指定した階層までを出力。例えば 2 を指定すると、最上位と直下の子カテゴリまでを出力。
  
{{Parameter|tab_index|整数|ドロップダウンメニューの <tt>select</tt> 要素に '<tt>tabindex</tt>' 属性を付ける。|オプション|0}}
+
{{Parameter|tab_index|整数|ドロップダウンメニューの <tt>select</tt> 要素に付ける '<tt>tabindex</tt>' 属性の値。|オプション|0}}
  
 
{{Parameter|name|文字列|ドロップダウンメニューのフォーム名(<tt>select</tt> 要素の '<tt>name</tt>' 属性)。|オプション|'cat'}}
 
{{Parameter|name|文字列|ドロップダウンメニューのフォーム名(<tt>select</tt> 要素の '<tt>name</tt>' 属性)。|オプション|'cat'}}
112行目: 117行目:
 
{{Parameter|hierarchical|真偽値|カテゴリーをフラットに表示する (0/False) または、階層形式(子孫カテゴリーをインデント)で表示する (1/True)|オプション|0/False}}
 
{{Parameter|hierarchical|真偽値|カテゴリーをフラットに表示する (0/False) または、階層形式(子孫カテゴリーをインデント)で表示する (1/True)|オプション|0/False}}
  
'''参考''':階層形式にすると '<tt>depth</tt>' 引数で指定する階層までを表示する。
+
'''参考''':階層形式 (hierarchical=true) にすると '<tt>depth</tt>' 引数で指定する階層までを表示する。
  
 
{{Parameter|pad_counts|真偽値|リンク数または投稿数を計算するとき、子孫カテゴリーからの数値を含める。'<tt>show_counts</tt>' と '<tt>hierarchical</tt>' が両方とも true の場合、この引数は自動的に true に設定される。|オプション|0/False}}
 
{{Parameter|pad_counts|真偽値|リンク数または投稿数を計算するとき、子孫カテゴリーからの数値を含める。'<tt>show_counts</tt>' と '<tt>hierarchical</tt>' が両方とも true の場合、この引数は自動的に true に設定される。|オプション|0/False}}
  
{{Parameter|taxonomy|文字列|指定したタクソノミーを返す。有効な値は '<tt>category</tt>'(カテゴリー)、'<tt>post_tag</tt>'(タグ)、または登録済みの[[カスタム分類]](タクソノミー)。|オプション|category}}
+
{{Parameter|taxonomy|文字列|指定したタクソノミーを返す。有効な値は:<ul><li>'<tt>category</tt>'(カテゴリー)</li><li>'<tt>post_tag</tt>'(タグ)</li><li>登録済みの[[カスタム分類]](タクソノミー)</li></ul>|オプション|category}}
  
 
{{Parameter|hide_if_empty|真偽値|ターム(例:カテゴリー、投稿タグ、カスタム分類の項目)が一つも無いときにフォーム自体を非表示にする (1/True) または、表示する (0/False)|オプション|0/False}}
 
{{Parameter|hide_if_empty|真偽値|ターム(例:カテゴリー、投稿タグ、カスタム分類の項目)が一つも無いときにフォーム自体を非表示にする (1/True) または、表示する (0/False)|オプション|0/False}}

2014年8月7日 (木) 20:49時点における版

送信ボタンのないセレクトボックス(ドロップダウンメニューなど)を使ったカテゴリーリストを表示します。

使い方

<?php wp_dropdown_categories( $args ); ?>

デフォルトの使い方

<?php $args = array(
	'show_option_all'    => '',
	'show_option_none'   => '',
	'orderby'            => 'ID', 
	'order'              => 'ASC',
	'show_count'         => 0,
	'hide_empty'         => 1, 
	'child_of'           => 0,
	'exclude'            => '',
	'echo'               => 1,
	'selected'           => 0,
	'hierarchical'       => 0, 
	'name'               => 'cat',
	'id'                 => '',
	'class'              => 'postform',
	'depth'              => 0,
	'tab_index'          => 0,
	'taxonomy'           => 'category',
	'hide_if_empty'      => false,
); ?>

デフォルトでは次のように表示します:

  • カテゴリー ID の昇順にソート
  • 最終更新日は非表示
  • 各カテゴリーの投稿数は非表示
  • 空の(投稿のない)カテゴリーは非表示
  • 除外カテゴリーなし
  • カテゴリーを表示(表示するか値として返すか選べるので)
  • フォームの 'selected'(初期選択値)とするカテゴリーなし
  • カテゴリーを階層型構造で表示しない
  • フォーム名を 'cat' とする
  • フォーム内のカテゴリーの ID 属性を指定しないため(デフォルトの)カテゴリー名が入る
  • フォームのクラスを 'postform' とする
  • 階層の深さ制限なし
  • フォームの tabindex を 0 にする
  • タクソノミーを 'category' にする
  • カテゴリー(タクソノミー 'category' のターム)が一つも無ければフォーム自体を非表示

パラメータ

$args
文字列|配列) (オプション) デフォルトの引数を上書きします。下記の引数を参照してください。
初期値:

戻り値

(文字列) 
'echo' 引数が 0 の場合のみ HTML コンテンツを返します。

引数

show_option_all
文字列) (オプション) クリックすると 'すべてのカテゴリー' を選択できるテキスト。デフォルトでは、'すべてのカテゴリー' を選択できるテキストを表示しない。
初期値: ''
show_option_none
文字列) (オプション) クリックすると 'カテゴリーなし' を指定できるテキスト。デフォルトでは、'カテゴリーなし' を指定できるテキストを表示しない。
初期値: ''
orderby
文字列) (オプション) カテゴリーをソートするためのキー項目。有効な値は:
  • 'ID'
  • 'NAME'(名前)
  • 'SLUG'(スラッグ)
初期値: 'ID'
order
文字列) (オプション) カテゴリーをソートする方向。有効な値は:
  • 'ASC'(昇順)
  • 'DESC'(降順)
初期値: 'ASC'
show_count
真偽値) (オプション) 各カテゴリーに属する投稿数を表示する (1/True) または、しない (0/False)
初期値: 0/False
hide_empty
真偽値) (オプション) 投稿のないカテゴリーを表示する (0/False) または、しない (1/True)
初期値: 1/True
child_of
整数) (オプション) カテゴリーを ID で指定して、その子孫のすべてのカテゴリー(子、孫、ひ孫・・・)を表示する。get_categories() を参照。
初期値: 0
exclude
文字列) (オプション) 除外したいカテゴリー ID をカンマ区切りで指定。
初期値: ''

参考:例えば 'exclude=4,12' とすれば、ID が 4 と 12 のカテゴリーを表示しない、または値として返さない。 get_categories() を参照。

exclude_tree
文字列) (オプション) カンマ区切りのリストで、除外したい親カテゴリーの ID を定義する。ある親カテゴリーとその子カテゴリーすべてを除外したい時に使う。hierarchical 引数が true の場合は、exclude 引数の値を使って exclude_tree と同じ処理が実行される。
初期値: ''

参考:例えば 'exclude_tree=5' を指定すると、ID が 5 のカテゴリーとその子(すべての子孫)カテゴリーが除外される。

echo
真偽値) (オプション) カテゴリーリストを表示する (1/True) または、PHP で使うために値を返す (0/False)
初期値: 1/True
depth
整数) (オプション) カテゴリー階層のどのレベルまでを出力するかを指定。hierarchical 引数が true でなければ、これは無視される。
初期値: 0

参考:depth

  • 0 - 全ての階層のカテゴリーを出力
  • -1 - 全てのカテゴリーをフラット(インデントなし)形式で出力(hierarchical 引数よりも優先)
  • 1 - 最上位カテゴリーのみ出力
  • 2以上 - 指定した階層までを出力。例えば 2 を指定すると、最上位と直下の子カテゴリまでを出力。
tab_index
整数) (オプション) ドロップダウンメニューの select 要素に付ける 'tabindex' 属性の値。
初期値: 0
name
文字列) (オプション) ドロップダウンメニューのフォーム名(select 要素の 'name' 属性)。
初期値: 'cat'
id
文字列) (オプション) ドロップダウンメニューの ID(select 要素の 'id' 属性)。
初期値: 'name'
class
文字列) (オプション) ドロップダウンメニューのクラス(select 要素の 'class' 属性)。
初期値: 'postform'
selected
整数) (オプション) 表示ボックスで 'selected' としたいカテゴリーの ID(これを付けるとドロップダウンメニューなどの選択値の初期値となる)。
初期値: 0(どれにも付けない)
hierarchical
真偽値) (オプション) カテゴリーをフラットに表示する (0/False) または、階層形式(子孫カテゴリーをインデント)で表示する (1/True)
初期値: 0/False

参考:階層形式 (hierarchical=true) にすると 'depth' 引数で指定する階層までを表示する。

pad_counts
真偽値) (オプション) リンク数または投稿数を計算するとき、子孫カテゴリーからの数値を含める。'show_counts' と 'hierarchical' が両方とも true の場合、この引数は自動的に true に設定される。
初期値: 0/False
taxonomy
文字列) (オプション) 指定したタクソノミーを返す。有効な値は:
  • 'category'(カテゴリー)
  • 'post_tag'(タグ)
  • 登録済みのカスタム分類(タクソノミー)
初期値: category
hide_if_empty
真偽値) (オプション) ターム(例:カテゴリー、投稿タグ、カスタム分類の項目)が一つも無いときにフォーム自体を非表示にする (1/True) または、表示する (0/False)
初期値: 0/False

用例

WordPress サイドバーの箇条書きリスト内に、送信ボタン付きの HTML フォームとして、階層型カテゴリーのドロップダウンリストを表示します。 各カテゴリーの投稿数も表示します。

<li id="categories">
	<h2><?php _e('Categories:'); ?></h2>
	<form action="<?php bloginfo('url'); ?>" method="get">
	<div>
	<?php wp_dropdown_categories('show_count=1&hierarchical=1'); ?>
	<input type="submit" name="submit" value="view" />
	</div>
	</form>
</li>

これは show_option_none パラメータを使った例です。 Moshu さんのフォーラムの投稿から転載しました。

<li id="categories"><h2><?php _e('Posts by Category'); ?></h2>
	<?php wp_dropdown_categories('show_option_none=Select category'); ?>

<script type="text/javascript"><!--
    var dropdown = document.getElementById("cat");
    function onCatChange() {
		if ( dropdown.options[dropdown.selectedIndex].value > 0 ) {
			location.href = "<?php echo get_option('home');
?>/?cat="+dropdown.options[dropdown.selectedIndex].value;
		}
    }
    dropdown.onchange = onCatChange;
--></script>
</li>

この例は echo パラメータ (echo=0) を使っています。 簡単な preg_replace を使って JavaScript のコードを追加しています。 JavaScript が使えない環境でも動作します(送信ボタンを noscript タグ内に埋め込んであるから)。

<li id="categories">
	<h2><?php _e('Posts by Category'); ?></h2>
	<form action="<?php bloginfo('url'); ?>/" method="get">
	<div>
<?php
$select = wp_dropdown_categories('show_option_none=Select category&show_count=1&orderby=name&echo=0');
$select = preg_replace("#<select([^>]*)>#", "<select$1 onchange='return this.form.submit()'>", $select);
echo $select;
?>
	<noscript><div><input type="submit" value="View" /></div></noscript>
	</div></form>
</li>

参考

  •  一度に複数の値を選べるようにするには、wp_category_checklist() を使ってください。
  •  結果の文字列を echo または返す前に wp_dropdown_cats フィルターが適用されます。

変更履歴

  • 2.9 : パラメータに pad_counts を追加
  • 2.7.1 : パラメータに exclude_tree を追加
  • 2.5 : パラメータに depth を追加
  • 2.1 : 新規テンプレートタグ

ソースファイル

wp_dropdown_categories()wp-includes/category-template.php にあります。


カテゴリータグ: the_category(), the_category_rss(), single_cat_title(), category_description(), wp_dropdown_categories(), wp_list_categories(), get_the_category(), get_the_category_by_ID(), get_category_by_slug(), get_the_category_list(), get_category_parents(), get_category_link(), is_category(), in_category()


リスト・ドロップダウン関数: wp_list_authors(), wp_list_categories(), wp_list_pages(), wp_list_bookmarks(), wp_list_comments(), wp_get_archives(), wp_page_menu(), wp_dropdown_pages(), wp_dropdown_categories(), wp_dropdown_users()


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


最新英語版: WordPress Codex » Function Reference/wp_dropdown_categories最新版との差分