WordPress как на ладони
Недорогой хостинг для сайтов на WordPress: wordpress.jino.ru

register_taxonomy() WP 2.3

Добавляет (регистрирует) новую (пользовательскую) таксономию. Можно перезаписать существующую таксономию.

Функцию желательно вызывать во время события init:

add_action( 'init', 'function_name' );

В качестве названия для новой таксономии нужно указывать уникальное имя, отличное от уже имеющихся таксономий, типов постов и зарезервированных WordPress публичных и частных переменных.

Полный список названий (черный список), которые не могут быть использованы, в качестве имени новой таксономии.

Когда нужно зарегистрировать новый тип записи, используйте register_post_type()

Удобный плагин, который позволяет регистрировать новые типы записей и таксономии: Custom Post Type UI

Работает на основе: WP_Taxonomy()
Хуки из функции
Возвращает

WP_Error/null.

Шаблон использования

// хук для регистрации
add_action( 'init', 'create_taxonomy' );
function create_taxonomy(){

	// список параметров: wp-kama.ru/function/get_taxonomy_labels
	register_taxonomy( 'taxonomy', [ 'post' ], [ 
		'label'                 => '', // определяется параметром $labels->name
		'labels'                => [
			'name'              => 'Genres',
			'singular_name'     => 'Genre',
			'search_items'      => 'Search Genres',
			'all_items'         => 'All Genres',
			'view_item '        => 'View Genre',
			'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',
		],
		'description'           => '', // описание таксономии
		'public'                => true,
		// 'publicly_queryable'    => null, // равен аргументу public
		// 'show_in_nav_menus'     => true, // равен аргументу public
		// 'show_ui'               => true, // равен аргументу public
		// 'show_in_menu'          => true, // равен аргументу show_ui
		// 'show_tagcloud'         => true, // равен аргументу show_ui
		// 'show_in_quick_edit'    => null, // равен аргументу show_ui
		'hierarchical'          => false,

		'rewrite'               => true,
		//'query_var'             => $taxonomy, // название параметра запроса
		'capabilities'          => array(),
		'meta_box_cb'           => null, // html метабокса. callback: `post_categories_meta_box` или `post_tags_meta_box`. false — метабокс отключен.
		'show_admin_column'     => false, // авто-создание колонки таксы в таблице ассоциированного типа записи. (с версии 3.5)
		'show_in_rest'          => null, // добавить в REST API
		'rest_base'             => null, // $taxonomy
		// '_builtin'              => false,
		//'update_count_callback' => '_update_post_term_count',
	] );
}

Использование

register_taxonomy( $taxonomy, $object_type, $args );
$taxonomy(строка) (обязательный)
Название создаваемой таксономии.
Может содержать только строчные латинские символы, числа и _, т.е. a-z0-9_. Длина названия таксономии должна быть в пределах от 1 до 32 символов (ограничение базы данных).
$object_type(строка/массив) (обязательный)
Название типов постов, к которым будет привязана таксономия. В этом параметре, например, можно указать 'post', тогда у обычных постов WordPress появится новая таксономия (возможность классификации).
$args(массив/строка/объект)
Аргументы, определяющие признаки таксономии. Переданные аргументы проходят через функцию wp_parse_args().
По умолчанию: array()

Аргументы параметра $args

label(строка)
Название таксономии во множественном числе (для отображения в админке).
По умолчанию: используется значение аргумента $labels->name
labels(массив)

Массив описывающий заголовки таксономии (для отображения в админке).

По умолчанию используются заголовки "меток" для не древовидных типов таксономий и заголовки "категорий" для древовидных таксономий.

  • name
    Имя таксономии, обычно во множественном числе. По умолчанию _x( 'Post Tags', 'taxonomy general name' ) или _x( 'Categories', 'taxonomy general name' );

  • singular_name
    Название для одного элемента этой таксономии. По умолчанию _x( 'Post Tag', 'taxonomy singular name' ) или _x( 'Category', 'taxonomy singular name' );

  • menu_name
    Текст для названия меню. Эта строка обозначает название для пунктов меню. По умолчанию значение параметра name;

  • search_items
    Текст для поиска элемента таксономии. По умолчанию __( 'Search Tags' ) или __( 'Search Categories' );

  • popular_items
    Текст для блока популярных элементов. __( 'Popular Tags' ) или null;

  • all_items
    Текст для всех элементов. __( 'All Tags' ) или __( 'All Categories' );

  • parent_item
    Текст для родительского элемента таксономии. Этот аргумент не используется для не древовидных таксономий. По умолчанию null или __( 'Parent Category' );

  • parent_item_colon
    Текст для родительского элемента таксономии, тоже что и parent_item но с двоеточием в конце. По умолчанию нет или __( 'Parent Category:' );

  • edit_item
    Текст для редактирования элемента. По умолчанию __( 'Edit Tag' ) или __( 'Edit Category' );

  • update_item
    Текст для обновления элемента. По умолчанию __( 'Update Tag' ) или __( 'Update Category' );

  • add_new_item
    Текст для добавления нового элемента таксономии. По умолчанию __( 'Add New Tag' ) или __( 'Add New Category' );

  • view_item
    Текст для просмотра термина таксономии. По умолчанию: "Посмотреть метку", "Посмотреть категорию". Используется например, в админ баре (тулбаре).

  • new_item_name
    Текст для создания нового элемента таксономии. По умолчанию __( 'New Tag Name' ) или __( 'New Category Name' );

  • separate_items_with_commas
    Текст описывающий, что элементы нужно разделять запятыми (для блога в админке). Не работает для древовидного типа. По умолчанию __( 'Separate tags with commas' ) или null;

  • add_or_remove_items
    Текст для "удаления или добавления элемента", который используется в блоке админке, при отключенном javascript. Не действует для древовидных таксономий. По умолчанию __( 'Add or remove tags' ) или null;

  • choose_from_most_used
    текст для блога при редактировании поста "выберите из часто используемых". Не используется для древовидных таксономий. По умолчанию __( 'Choose from the most used tags' ) или null;

  • popular_items
    Текст для поиска популярных терминов. Этот параметр не используется для древовидных таксономий. По умолчанию: "Популярные метки" или null.

  • separate_items_with_commas
    Текст говорящий о том, что термины (метки) нужно разделять запятыми. Не используется для древовидных таксономий. По умолчанию: "Разделяйте метки запятыми" или null.

  • add_or_remove_items
    Текст для добавления или удаления терминов. Не используется для древовидных типов. По умолчанию: "Добавить или удалить метки". или null.

  • choose_from_most_used
    Текст "Выбрать из часто используемых". Не используется для древовидных типов.

  • not_found
    Текст "не найдено", который отображается, если при клике на часто используемые ни один термин не был найден.

Весь список смотрите в описании get_taxonomy_labels()

По умолчанию: заголовки меток/категорий

public(логический)
Показывать ли эту таксономию в интерфейсе админ-панели. Это значение передается параметрам publicly_queryable, show_ui, show_in_nav_menus если для них не установлено свое значение.
По умолчанию: true
show_ui(логический)
Показывать блок управления этой таксономией в админке.
По умолчанию: если нет, равно аргументу public
show_in_menu(логический)

Показывать ли таксономию в админ-меню.

  • true - таксономия будет показана как подменю у типа записи, к которой она прикреплена.
  • false - подменю не будет показано.

Параметр $show_ui должен быть включен (true).

По умолчанию: если нет, равно аргументу show_ui

show_in_nav_menus(логический)
true даст возможность выбирать элементы этой таксономии в навигационном меню.
По умолчанию: если нет, равно аргументу public
show_tagcloud(логический)
Создать виджет облако элементов этой таксономии (как облако меток).
По умолчанию: если нет, равно аргументу show_ui
show_in_rest(логический) (WP 4.7)

Нужно ли включать таксономию в REST API.

Также влияет на работу блочного редактора Gutenberg: true - таксономия будет видна в редакторе блоков Gutenberg, false - такса будет видна только в обычном редакторе.

rest_base(строка) (WP 4.7)
Ярлык в REST API. По умолчанию, название таксономии.
По умолчанию: $taxonomy
rest_controller_class(строка) (WP 4.7)
Название класса контроллера в REST API.
По умолчанию: 'WP_REST_Terms_Controller'
hierarchical(логический)
true - таксономия будет древовидная (как категории). false - будет не древовидная (как метки).
По умолчанию: false
update_count_callback(строка)

Название функции, которая будет вызываться для обновления количества записей в данной таксономии (у термина), для типа записи ассоциированного с этой таксономией.

По умолчанию:

  • _update_post_term_count для таксономий прикрепленных к типам записей.
  • _update_generic_term_count для таксономий, присоединенных к другим объектам, например, к юзерам.

Функция получит следующие параметры:

  • $termsterm_taxonomy_id терминов которые нужно обновить.
  • $taxonomy — Объект таксономии.

По умолчанию: '_update_post_term_count' или '_update_generic_term_count'

rewrite(массив/логический)

false - отключит перезапись. Если указать массив, то можно задать произвольный параметр запроса (query var). А по умолчанию будет использоваться параметр $taxonomy.

Возможные аргументы массива:

  • slug - предваряет таксономии этой строкой. По умолчанию название таксономии;
  • with_front - позволяет установить префикс для постоянной ссылки. По умолчанию true;
  • hierarchical - true - включает поддержку древовидных URL (с версии 3.1). По умолчанию false;

Массив передается в функцию add_permastruct(), поэтому тут также можно указать аргументы этой функции.

По умолчанию: true

publicly_queryable(логический)
Имеют ли пользователи доступ к элементам таксономии во внешней части сайта. Если не установлено, то берется значение параметра public. C версии 4.5.
По умолчанию: null (равен аргументу public)
query_var(строка/логический)
Если указать false, выключит параметры запроса и сам запрос. Или можно указать строку, чтобы изменить параметр запроса (query var). По умолчанию будет использоваться параметр $taxonomy - название таксономии.
По умолчанию: $taxonomy
capabilities(массив)

Массив прав для этой таксономии:

  • manage_terms - 'manage_categories'
  • edit_terms - 'manage_categories'
  • delete_terms - 'manage_categories'
  • assign_terms - 'edit_posts'

По умолчанию: нет

meta_box_cb(строка)

callback функция. Отвечает за то, как будет отображаться таксономия в метабоксе (с версии 3.8).

Встроенные названия функций:

  • post_categories_meta_box - показывать как категории
  • post_tags_meta_box - показывать как метки.

Если указать false, то метабокс будет отключен вообще.

По умолчанию: null

show_admin_column(логический)
Позволить или нет авто-создание колонки таксономии в таблице ассоциированного типа записи. (с версии 3.5)
По умолчанию: false
show_in_quick_edit(логический)
Показывать ли таксономию в панели быстрого редактирования записи (в таблице, списке всех записей, при нажатии на кнопку "свойства"). С версии 4.2.
По умолчанию: null (значение show_ui)
sort(логический)

Следует ли этой таксономии запоминать порядок в котором созданные элементы (термины) прикрепляются к объектам (записям).

Например, для тегов, если этот параметр true, то при получении тегов они должны выводиться в том порядке, в котором они были указаны (добавлены) для записи. Т.е. если этот флаг установлен, то сортировка терминов должна быть не по name а по полю term_order.

При true в таблицу wp_term_relationships в поле term_order будет записываться число - порядок в котором расположены рубрики, в которые добавлена запись. Чаще всего эта настройка не нужна, более того, параметр этот есть, но в коде он нигде не прописан и по факту ни на что не виляет.
По умолчанию: null

_builtin(логический) (не для обычного использования)
Параметр предназначен для разработчиков. Если переключить на true, то это будет означать что эта таксономия относится к внутренним таксономия WordPress и не является встроенной (кастомной).
По умолчанию: false

Примеры

#1. Регистрация таксономий

Пример регистрации двух таксономий "genres" и "writers" для постов типа "book". Этот код можно вставить в файл темы functions.php. Некоторые аргументы рассчитаны на версию 3.1+:

// хук, через который подключается функция
// регистрирующая новые таксономии (create_book_taxonomies)
add_action( 'init', 'create_book_taxonomies' );

// функция, создающая 2 новые таксономии "genres" и "writers" для постов типа "book"
function create_book_taxonomies(){

	// Добавляем древовидную таксономию 'genre' (как категории)
	register_taxonomy('genre', array('book'), array(
		'hierarchical'  => true,
		'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' ),
		),
		'show_ui'       => true,
		'query_var'     => true,
		//'rewrite'       => array( 'slug' => 'the_genre' ), // свой слаг в URL
	));

	// Добавляем НЕ древовидную таксономию 'writer' (как метки)
	register_taxonomy('writer', 'book',array(
		'hierarchical'  => false,
		'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' ),
			'menu_name'                   => __( 'Writers' ),
		),
		'show_ui'       => true,
		'query_var'     => true,
		//'rewrite'       => array( 'slug' => 'the_writer' ), // свой слаг в URL
	));
}

#2 Добавление таксономии в ЧПУ

Смотрите в примерах к описаниям функций: register_post_type(), WP_Rewrite

#3 Переименования названий таксономии

Код ниже, показывает как переименовать имеющуюся таксономию category (рубрики).

## Переименуем таксономию category (рубрики)
add_action( 'init', function(){
	global $wp_taxonomies;

	$labels                     = & $wp_taxonomies['category']->labels;
	$labels->name               = 'Author';
	$labels->singular_name      = 'Author';
	$labels->add_new            = 'Add Author';
	$labels->add_new_item       = 'Add Author';
	$labels->edit_item          = 'Edit Author';
	$labels->new_item           = 'Author';
	$labels->view_item          = 'View Author';
	$labels->search_items       = 'Search Authors';
	$labels->not_found          = 'No Authors found';
	$labels->not_found_in_trash = 'No Authors found in Trash';
	$labels->all_items          = 'All Authors';
	$labels->menu_name          = 'Author';
	$labels->name_admin_bar     = 'Author';

} );

Заметки

  • Global. Массив. $wp_taxonomies Registered taxonomies.

Список изменений

С версии 2.3.0 Введена.
С версии 4.2.0 Introduced show_in_quick_edit argument.
С версии 4.4.0 The show_ui argument is now enforced on the term editing screen.
С версии 4.4.0 The public argument now controls whether the taxonomy can be queried on the front end.
С версии 4.5.0 Introduced publicly_queryable argument.
С версии 4.7.0 Introduced show_in_rest, 'rest_base' and 'rest_controller_class' arguments to register the Taxonomy in REST API.
С версии 5.1.0 Introduced meta_box_sanitize_cb argument.
С версии 5.4.0 Added the registered taxonomy object as a return value.

Код register taxonomy: wp-includes/taxonomy.php WP 5.4.2

<?php
function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
	global $wp_taxonomies;

	if ( ! is_array( $wp_taxonomies ) ) {
		$wp_taxonomies = array();
	}

	$args = wp_parse_args( $args );

	if ( empty( $taxonomy ) || strlen( $taxonomy ) > 32 ) {
		_doing_it_wrong( __FUNCTION__, __( 'Taxonomy names must be between 1 and 32 characters in length.' ), '4.2.0' );
		return new WP_Error( 'taxonomy_length_invalid', __( 'Taxonomy names must be between 1 and 32 characters in length.' ) );
	}

	$taxonomy_object = new WP_Taxonomy( $taxonomy, $object_type, $args );
	$taxonomy_object->add_rewrite_rules();

	$wp_taxonomies[ $taxonomy ] = $taxonomy_object;

	$taxonomy_object->add_hooks();

	/**
	 * Fires after a taxonomy is registered.
	 *
	 * @since 3.3.0
	 *
	 * @param string       $taxonomy    Taxonomy slug.
	 * @param array|string $object_type Object type or array of object types.
	 * @param array        $args        Array of taxonomy registration arguments.
	 */
	do_action( 'registered_taxonomy', $taxonomy, $object_type, (array) $taxonomy_object );

	return $taxonomy_object;
}

Cвязанные функции

Из метки: Расширения WP (доп возможности регистрация)

Еще из раздела: Любые таксономии

76 комментов
Полезные 8 Вопросы 5 Все
  • Александр

    Помогите разобраться, почему при переходе на страницу архива /files/ подключается правильный файл архива archive-files.php, а если зайти в категорию файлов, например /files/dodatky/ то подгружается обычный файл archive.php

    // функция, создающая таксономию
    function create_files_taxonomies(){
    
    	register_taxonomy('filescategory', array('files'), array(
    		'hierarchical'  => true,
    		'labels'        => array(
    			'name'              => 'Категорії',
    			'singular_name'     => 'Категорія',
    			'search_items'      => 'Search Genres',
    			'all_items'         => 'Усі категорії',
    			'view_item '        => 'View Genre',
    			'parent_item'       => 'Parent Genre',
    			'parent_item_colon' => 'Parent Genre:',
    			'edit_item'         => 'Редагудувати категорію',
    			'update_item'       => 'Update Genre',
    			'add_new_item'      => 'Add New Genre',
    			'new_item_name'     => 'New Genre Name',
    			'menu_name'         => 'Категорії',
    		),
    		'show_ui'       => true,
    		'query_var'     => true,
    		'rewrite'       => array( 'slug' => 'files', 'with_front' => false, 'hierarchical' => true ), 
    	));
    }
    
    Ответить18.Дек.2019 18:01 #
  • Александр

    Зарегистрировал таксономию city. Нужно сделать, чтобы при выборе города в урл страницы добавлялся город на все страницы сайта, например было site.ru/categoryname/postname/ стало site.ru/moskva/categoryname/postname/. И чтобы по ссылкам показывались посты и страницы в которых в таксономии city выбран город Моксва. Думаю сделать чтобы после выбора города, переменная с городом сохранялась в сессию и дальше ее уже добавлять в урл. Только не могу сообразить как это правильно сделать.

    Ответить21.Дек.2019 12:46 #