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

「利用者:Gblsm/関数リファレンス/register taxonomy」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(ページの作成:「{{Draft}} <div id="Description"> == 説明 == </div> この関数はタクソノミーを (カスタム分類として) 追加したり、上書きしたりします...」)
 
1行目: 1行目:
 +
{{Notice||翻訳の途中です。オリジナルは 15:55, 8 July 2014 Jdgrimes #144732 です。}}
 +
<!-- http://codex.wordpress.org/Function_Reference/register_taxonomy -->
 +
<!-- http://wpdocs.sourceforge.jp/関数リファレンス/register_taxonomy -->
 
{{Draft}}
 
{{Draft}}
  

2014年7月17日 (木) 22:27時点における版

お知らせ: 翻訳の途中です。オリジナルは 15:55, 8 July 2014 Jdgrimes #144732 です。このページのノートをご覧ください。

このページはラフドラフトで、まだ内容の検証が済んでいません。情報が間違っていたり書き直されることがあります。
執筆中のため、執筆者の許可なく編集しないでください

この関数はタクソノミーを (カスタム分類として) 追加したり、上書きしたりします。 タクソノミーの名前、対象とするオブジェクトの名前、それから引数の配列をパラメータとします。 何も値を返しません。

タクソノミーの名前は注意深く選んで、他のタクソノミーや投稿、それから WordPress の public/private クエリ変数 と衝突しないようにします。 このページにある予約語セクションでチェックしてください。 特に大文字は禁止です(バージョン 3.0 では許されていましたが、バージョン 3.1 からは "Cheatin'" エラーが出ます)。

使い方

<?php register_taxonomy( $taxonomy, $object_type, $args ); ?>

この関数は init アクションを使って呼び出してください。 アクションの外から呼び出すとトラブルの元になります。 詳しくは チケット #15568 を参照してください。

カスタム投稿タイプにカスタムタクソノミー(カスタム分類)を登録するときは安全第一を心がけてください。 この関数でタクソノミーとオブジェクトを繋いだ後、すぐに register_taxonomy_for_object_type() を呼び出してください。 これを怠ると、parse_requestpre_get_posts の中でフィルター呼び出しが行われるときに投稿タイプが不明になってしまい、どんな結果になるかわかりません。

パラメータ

$taxonomy
文字列) (必須) タクソノミーの名前。英小文字とアンダースコアのみ、32文字以下(データベース構造による制限)。
初期値: なし
$object_type
配列/文字列) (必須) タクソノミーオブジェクトのオブジェクト名。オブジェクトタイプは WordPress 標準の投稿タイプ、または登録されているカスタム投稿タイプ
初期値: なし
標準の投稿タイプ:
  • post
  • page
  • attachment
  • revision
  • nav_menu_item
カスタム投稿タイプ:
  • {custom_post_type} - カスタム投稿タイプの名前は英小文字とし、空白は禁止です。
  • null - 明示的に null をセットすると、タクソノミーは登録されますがどのオブジェクトにも関連付けられないため、管理画面から直接使うことはできません。その場合、カスタム投稿タイプを登録するときに 'taxonomy' パラメータを使うか( $args に入れて渡す。register_post_type() を参照)、それとも register_taxonomy_for_object_type() を使って改めて登録する必要があります。
$args
配列/文字列) (オプション引数の配列
初期値: なし

引数

label
文字列) (オプション) タクソノミーの複数形の名前。翻訳の対象。
初期値: $labels->name で上書きされる。
labels
配列) (オプション) タクソノミーに付けるラベルの配列。デフォルトでは、階層のないタクソノミーにはタグのラベルが、階層化したタクソノミーにはカテゴリーのラベルが使われる。
初期値: 空(指定しない)の場合、label の値が name に入り、name の値が singular_name に入る。
  • 'name' - タクソノミーの一般的な名前、普通は複数形。 $tax->label によって上書きされて同じになる。デフォルトは _x( 'Post Tags', 'taxonomy general name' ) または _x( 'Categories', 'taxonomy general name' ) 。この文字列を国際化するときは、gettext context を使用してカスタム投稿タイプに合わせてください。例: _x('Writers', 'taxonomy general name');
  • 'singular_name' - タクソノミーのオブジェクト 1 個の名前。デフォルトは _x( 'Post Tag', 'taxonomy singular name' ) または _x( 'Category', 'taxonomy singular name' ) 。この文字列を国際化するときは、gettext context を使用してカスタム投稿タイプに合わせてください。例: _x('Writer', 'taxonomy singular name');
  • 'menu_name' - the menu name text. This string is the name to give menu items. If not set, defaults to value of name label.
  • 'all_items' - the all items text. Default is __( 'All Tags' ) or __( 'All Categories' )
  • 'edit_item' - the edit item text. Default is __( 'Edit Tag' ) or __( 'Edit Category' )
  • 'view_item' - the view item text, Default is __( 'View Tag' ) or __( 'View Category' )
  • 'update_item' - the update item text. Default is __( 'Update Tag' ) or __( 'Update Category' )
  • 'add_new_item' - the add new item text. Default is __( 'Add New Tag' ) or __( 'Add New Category' )
  • 'new_item_name' - the new item name text. Default is __( 'New Tag Name' ) or __( 'New Category Name' )
  • 'parent_item' - the parent item text. This string is not used on non-hierarchical taxonomies such as post tags. Default is null or __( 'Parent Category' )
  • 'parent_item_colon' - The same as parent_item, but with colon : in the end null, __( 'Parent Category:' )
  • 'search_items' - the search items text. Default is __( 'Search Tags' ) or __( 'Search Categories' )
  • 'popular_items' - the popular items text. This string is not used on hierarchical taxonomies. Default is __( 'Popular Tags' ) or null
  • 'separate_items_with_commas' - the separate item with commas text used in the taxonomy meta box. This string is not used on hierarchical taxonomies. Default is __( 'Separate tags with commas' ), or null
  • 'add_or_remove_items' - the add or remove items text and used in the meta box when JavaScript is disabled. This string is not used on hierarchical taxonomies. Default is __( 'Add or remove tags' ) or null
  • 'choose_from_most_used' - the choose from most used text used in the taxonomy meta box. This string is not used on hierarchical taxonomies. Default is __( 'Choose from the most used tags' ) or null
  • 'not_found' (3.6+) - the text displayed via clicking 'Choose from the most used tags' in the taxonomy meta box when no tags are available. This string is not used on hierarchical taxonomies. Default is __( 'No tags found.' ) or null
public
真偽値) (オプション) If the taxonomy should be publicly queryable.
初期値: true
show_ui
真偽値) (オプション) Whether to generate a default UI for managing this taxonomy.
初期値: if not set, defaults to value of public argument. As of 3.5, setting this to false for attachment taxonomies will hide the UI.
show_in_nav_menus
真偽値) (オプション) true makes this taxonomy available for selection in navigation menus.
初期値: if not set, defaults to value of public argument
show_tagcloud
真偽値) (オプション) Whether to allow the Tag Cloud widget to use this taxonomy.
初期値: if not set, defaults to value of show_ui argument
meta_box_cb
callback) (オプション) Provide a callback function name for the meta box display. (Available since 3.8)
初期値: null

Note: Defaults to the categories meta box (post_categories_meta_box() in meta-boxes.php) for hierarchical taxonomies and the tags meta box (post_tags_meta_box()) for non-hierarchical taxonomies. No meta box is shown if set to false.

show_admin_column
真偽値) (オプション) Whether to allow automatic creation of taxonomy columns on associated post-types table. (Available since 3.5)
初期値: false
hierarchical
真偽値) (オプション) Is this taxonomy hierarchical (have descendants) like categories or not hierarchical like tags.
初期値: false

Note: Hierarchical taxonomies will have a list with checkboxes to select an existing category in the taxonomy admin box on the post edit page (like default post categories). Non-hierarchical taxonomies will just have an empty text field to type-in taxonomy terms to associate with the post (like default post tags).

update_count_callback
文字列) (オプション) A function name that will be called when the count of an associated $object_type, such as post, is updated. Works much like a hook.
初期値: None - but see Note, below.

Note: While the default is '', when actually performing the count update in wp_update_term_count_now(), if the taxonomy is only attached to post types (as opposed to other WordPress objects, like user), the built-in _update_post_term_count() function will be used to count only published posts associated with that term, otherwise _update_generic_term_count() will be used instead, that does no such checking.

This is significant in the case of attachments. Because an attachment is a type of post, the default _update_post_term_count() will be used. However, this may be undesirable, because this will only count attachments that are actually attached to another post (like when you insert an image into a post). This means that attachments that you simply upload to WordPress using the Media Library, but do not actually attach to another post will not be counted. If your intention behind associating a taxonomy with attachments was to leverage the Media Library as a sort of Document Management solution, you are probably more interested in the counts of unattached Media items, than in those attached to posts. In this case, you should force the use of _update_generic_term_count() by setting '_update_generic_term_count' as the value for update_count_callback.

query_var
真偽値または文字列) (オプション) False to disable the query_var, set as string to use custom query_var instead of default which is $taxonomy, the taxonomy's "name".
初期値: $taxonomy

Note: The query_var is used for direct queries through WP_Query like new WP_Query(array('people'=>$person_name)) and URL queries like /?people=$person_name. Setting query_var to false will disable these methods, but you can still fetch posts with an explicit WP_Query taxonomy query like WP_Query(array('taxonomy'=>'people', 'term'=>$person_name)).

rewrite
真偽値/配列) (オプション) Set to false to prevent automatic URL rewriting a.k.a. "pretty permalinks". Pass an $args array to override default URL settings for permalinks as outlined below:
初期値: true
  • 'slug' - Used as pretty permalink text (i.e. /tag/) - defaults to $taxonomy (taxonomy's name slug)
  • 'with_front' - allowing permalinks to be prepended with front base - defaults to true
  • 'hierarchical' - true or false allow hierarchical urls (implemented in Version 3.1) - defaults to false
  • 'ep_mask' - Assign an endpoint mask for this taxonomy - defaults to EP_NONE. For more info see this Make WordPress Plugins summary of endpoints.

Note: You may need to flush the rewrite rules after changing this. You can do it manually by going to the Permalink Settings page and re-saving the rules -- you don't need to change them -- or by calling $wp_rewrite->flush_rules(). You should only flush the rules once after the taxonomy has been created, not every time the plugin/theme loads.

capabilities
配列) (オプション) An array of the capabilities for this taxonomy.
初期値: なし
  • 'manage_terms' - 'manage_categories'
  • 'edit_terms' - 'manage_categories'
  • 'delete_terms' - 'manage_categories'
  • 'assign_terms' - 'edit_posts'
sort
真偽値) (オプション) Whether this taxonomy should remember the order in which terms are added to objects.
初期値: なし
_builtin
真偽値) (not for general use) Whether this taxonomy is a native or "built-in" taxonomy. Note: this Codex entry is for documentation - core developers recommend you don't use this when registering your own taxonomy
初期値: false

An example of registering a two taxonomies, genres and writers, for the post type called "book" (uses Version 3.1 arguments):

Note: You can define custom taxonomies in a themes's functions.php template file:

<?php
// hook into the init action and call create_book_taxonomies when it fires
add_action( 'init', 'create_book_taxonomies', 0 );

// create two taxonomies, genres and writers for the post type "book"
function create_book_taxonomies() {
	// Add new taxonomy, make it hierarchical (like categories)
	$labels = array(
		'name'              => _x( 'Genres', 'taxonomy general name' ),
		'singular_name'     => _x( 'Genre', 'taxonomy singular name' ),
		'search_items'      => __( 'Search Genres' ),
		'all_items'         => __( 'All Genres' ),
		'parent_item'       => __( 'Parent Genre' ),
		'parent_item_colon' => __( 'Parent Genre:' ),
		'edit_item'         => __( 'Edit Genre' ),
		'update_item'       => __( 'Update Genre' ),
		'add_new_item'      => __( 'Add New Genre' ),
		'new_item_name'     => __( 'New Genre Name' ),
		'menu_name'         => __( 'Genre' ),
	);

	$args = array(
		'hierarchical'      => true,
		'labels'            => $labels,
		'show_ui'           => true,
		'show_admin_column' => true,
		'query_var'         => true,
		'rewrite'           => array( 'slug' => 'genre' ),
	);

	register_taxonomy( 'genre', array( 'book' ), $args );

	// Add new taxonomy, NOT hierarchical (like tags)
	$labels = array(
		'name'                       => _x( 'Writers', 'taxonomy general name' ),
		'singular_name'              => _x( 'Writer', 'taxonomy singular name' ),
		'search_items'               => __( 'Search Writers' ),
		'popular_items'              => __( 'Popular Writers' ),
		'all_items'                  => __( 'All Writers' ),
		'parent_item'                => null,
		'parent_item_colon'          => null,
		'edit_item'                  => __( 'Edit Writer' ),
		'update_item'                => __( 'Update Writer' ),
		'add_new_item'               => __( 'Add New Writer' ),
		'new_item_name'              => __( 'New Writer Name' ),
		'separate_items_with_commas' => __( 'Separate writers with commas' ),
		'add_or_remove_items'        => __( 'Add or remove writers' ),
		'choose_from_most_used'      => __( 'Choose from the most used writers' ),
		'not_found'                  => __( 'No writers found.' ),
		'menu_name'                  => __( 'Writers' ),
	);

	$args = array(
		'hierarchical'          => false,
		'labels'                => $labels,
		'show_ui'               => true,
		'show_admin_column'     => true,
		'update_count_callback' => '_update_post_term_count',
		'query_var'             => true,
		'rewrite'               => array( 'slug' => 'writer' ),
	);

	register_taxonomy( 'writer', 'book', $args );
}
?>

基本的な例

<?php
add_action( 'init', 'create_book_tax' );

function create_book_tax() {
	register_taxonomy(
		'genre',
		'book',
		array(
			'label' => __( 'Genre' ),
			'rewrite' => array( 'slug' => 'genre' ),
			'hierarchical' => true,
		)
	);
}
?>

Note: If you want to ensure that your custom taxonomy behaves like a tag, you must add the option 'update_count_callback' => '_update_post_term_count'. Not doing so will result in multiple comma-separated items added at once being saved as a single value, not as separate values. This can cause undue stress when using get_the_term_list and other term display functions.

予約語

Avoiding the following reserved terms is particularly important if you are passing the term through the $_GET or $_POST array. Doing so can cause WordPress to respond with a 404 error without any other hint or explanation.

  • attachment
  • attachment_id
  • author
  • author_name
  • calendar
  • cat
  • category
  • category__and
  • category__in
  • category__not_in
  • category_name
  • comments_per_page
  • comments_popup
  • customize_messenger_channel
  • customized
  • cpage
  • day
  • debug
  • error
  • exact
  • feed
  • hour
  • link_category
  • m
  • minute
  • monthnum
  • more
  • name
  • nav_menu
  • nonce
  • nopaging
  • offset
  • order
  • orderby
  • p
  • page
  • page_id
  • paged
  • pagename
  • pb
  • perm
  • post
  • post__in
  • post__not_in
  • post_format
  • post_mime_type
  • post_status
  • post_tag
  • post_type
  • posts
  • posts_per_archive_page
  • posts_per_page
  • preview
  • robots
  • s
  • search
  • second
  • sentence
  • showposts
  • static
  • subpost
  • subpost_id
  • tag
  • tag__and
  • tag__in
  • tag__not_in
  • tag_id
  • tag_slug__and
  • tag_slug__in
  • taxonomy
  • tb
  • term
  • theme
  • type
  • w
  • withcomments
  • withoutcomments
  • year

変更履歴

  • 3.6.0:
    • Add 'not_found' label.
  • 3.5.0:
    • Setting 'show_ui' to false hides UI for attachment taxonomies.
    • Add 'show_admin_column' to allow automatic creation of taxonomy columns on associated post types.
  • Since: 2.3.0

ソースファイル

register_taxonomy() is located in wp-includes/taxonomy.php.

参考サイト

register_post_type()


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