register_taxonomy() WP 2.3.0

Створює нову довільну таксономію WordPress. Дозволяє змінити існуючу таксономію.

Функція дозволяє додати (зареєструвати) користувальницьку таксономію WP або змінити дані таксономії, яка вже була зареєстрована.

При зміні існуючої таксономії значення параметра $object_type із початкової реєстрації буде перезаписано. Тому, його важливо вказати заново таке ж, як було або нове.

Таксономія – це можливість класифікувати об’єкти, наприклад рубрики для постів. Читайте докладніше про таксономію .

Не рекомендується викликати функцію до події init :

add_action('init', 'function_name');

Зарезервовані назви

У назві таксономії (параметр $taxonomy) або у параметрі query_var не можна використовувати зарезервовані імена WordPress. Наприклад, не можна вказувати author.

Це особливо важливо, якщо ви передаєте назву через масив $_GET або $_POST. Це може призвести до того, що WordPress відповість помилкою 404 без будь-яких інших підказок.

attachment
attachment_id
author
author_name
calendar
cat
category
category_name
custom
customize_messenger_channel
customized
cpage
day
debug
embed
error
exact
feed
fields
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_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
status
subpost
subpost_id
tag
tag_id
taxonomy
tb
term
terms
theme
title
type
types
w
withcomments
withoutcomments
year

Повний список зарезервованих назв (чорний список) , які не можна використовувати, як ім’я нової таксономії або параметри, що стосуються запиту.

Рекомендується спочатку реєструвати таксономію, а потім тип запису, з яким ця таксономія пов’язана!

Ця особливість у деяких випадках позбавить вас від багів та купи витраченого часу.

// правильний порядок реєстрації типу запису та її таксономії
register_taxonomy(...);
register_post_type(...);

Прив’язати таксономію до типу запису можна пізніше – після виклику цієї функції за допомогою register_taxonomy_for_object_type() .

Встановіть параметр show_in_rest = true, щоб панель таксономії з’явилася на бічній панелі редактора блоків.

Використовуйте register_post_type() , коли потрібно зареєструвати новий тип запису.

Зручний плагін, який дозволяє реєструвати нові типи записів та таксономії: Custom Post Type UI

Працює на основі:
WP_Taxonomy()

Повертає

WP_Taxonomy|WP_Error. Зареєстрований об’єкт таксономії WP_Error при невдачі.

Шаблон використання

// хук для реєстрації
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',
			'back_to_items' => '← Back to 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 з’явиться нова таксономія.

Назви типів постів мають бути написані в нижньому регістрі та без пробілів. Максимальна дозволена довжина 20 символів.

  • null– Установка null реєструє таксономію, але не пов’язує її з жодним об’єктом, тому вона не буде доступна в інтерфейсі адмін-панелі. Зв’язати об’єкт і таксономію можна буде пізніше під час реєстрації типу запису в параметрі ‘taxonomy’: див. register_taxonomy_for_object_type() .

Вбудовані типи постів WP:

  • post
  • page
  • attachment
  • revision
  • nav_menu_item
  • custom_css
  • customize_changeset
$args
(масив/рядок/об’єкт)
Аргументи (параметри) таксономії. Аргументи можна вказати рядком, тоді вони будуть оброблені функцією
wp_parse_args() .


За замовчуванням: array()

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


label
(рядок)
Назва таксономії у множині (для відображення в адмінці).


За промовчанням: використовується значення аргументу $labels->name

description
(рядок)
Короткий опис про таксономію (навіщо вона).


За замовчуванням: ”

labels
(масив)

Масив описує заголовки таксономії (для відображення в адмінці).

Весь список дивіться в описі get_taxonomy_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.

  • not_found
    Текст “не знайдено”, який відображається, якщо при натисканні на часто використовувані жоден термін не було знайдено.

  • back_to_items
    Текст “← Перейти до рубрик”. Мітка відображається після оновлення терміну.

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– такса буде видно лише у звичайному редакторі.

Типово: false


rest_base
(рядок) (WP 4.7)
Ярлик у REST API. За умовчанням назва таксономії.


За замовчуванням $taxonomy

rest_controller_class
(рядок) (WP 4.7)
Назва класу контролера у REST API.


За замовчуванням: ‘WP_REST_Terms_Controller’

rest_namespace
(рядок) (WP 5.9)
Вказує префікс (простір імен) у URL REST API маршруту.


За промовчанням wp/v2

hierarchical
(логічний)

true – таксономія буде деревоподібна (ієрархічна) – матиме checkbox’и на сторінці редагування посту (наприклад, категорії посту).

false – таксономія буде не деревоподібна (Не-ієрархічна) – матиме просто порожнє текстове поле для введення імені елемента таксономії (наприклад теги посту).

Типово: false


update_count_callback
(рядок)

Назва функції, яка буде викликатися для оновлення кількості записів в елементі таксономії (кількість записів терміна). Які записи підраховувати визначається зв’язком таксономії та типу посту.

За замовчуванням:

  • _update_post_term_count для таксономій, прикріплених до типів записів.
  • _update_generic_term_count для таксономій, приєднаних до інших об’єктів, наприклад, до користувачів.

Функція отримає такі параметри:

  • $termsterm_taxonomy_id термінів, які потрібно оновити.
  • $taxonomy – Об’єкт таксономії.

Підрахунок виконує функція _update_generic_term_count() , яка не робить такої перевірки.

Це важливо у випадку з вкладеннями (attachments). Оскільки вкладення – це тип повідомлення, за замовчуванням використовуватиметься _update_generic_term_count() . Для цього потрібно вказати '_update_generic_term_count'значення для update_count_callback .

Ще один важливий момент: функція _update_post_term_count() враховує лише опубліковані пости. Якщо ви використовуєте статуси користувача або типи постів, де опублікованість не важлива, вам потрібно буде створити свою функцію підрахунку і вказати її назву в цьому параметрі.

За замовчуванням: ” – ‘_update_post_term_count’ або ‘_update_generic_term_count’


rewrite
(масив/false)

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

Можливі аргументи масиву:

  • slug (рядок) – передує таксономії цим рядком. За промовчанням назва таксономії.
  • with_front (true/false) – дозволяє встановити префікс для постійного посилання. Типово true.
  • hierarchical (true/false) – true – включає підтримку деревоподібних URL (з версії 3.1). За промовчанням false.
  • ep_mask (число) – шаблон кінцевих точок. Типово: EP_NONE . (Потрібно для красивих пермалінків) Призначте маску кінцевої точки для таксономії – за замовчуванням EP_NONE. Якщо ви не вкажете EP_MASK, красиві пермалінки не працюватимуть. Додаткову інформацію можна знайти у статті Make WordPress Plugins summary of endpoints .

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

Після зміни цього параметра або при першій реєстрації таксономії потрібно перестворити правила перезапису. Це можна зробити вручну, просто перейшовши на сторінку Settings > Permalink. Або можна викликати функцію flush_rewrite_rules() . Це потрібно зробити лише один раз після реєстрації таксономії, а не при кожному запиті.

Типово: true


publicly_queryable
(логічний)
Чи мають користувачі доступ до елементів таксономії у зовнішній частині сайту. Якщо встановлено, то береться значення параметра
public . З версії 4.5.


Типово: null (рівний аргументу public)

query_var
(рядок/логічний)

Якщо вказати false, вимкне параметри запиту і сам запит. Тобто. WordPress не буде обробляти або розуміти запити, пов’язані з цією таксономією.

Якщо вказати рядок, то вона буде використовувати як параметр запиту, щоб отримати елементи цієї таксономії. За промовчанням вказується назва таксономії – параметр $taxonomy.

query_var використовується для запитів через WP_Query, таких як:

new WP_Query( [ 'people' => $person_name ] )

та URL-запитів типу /?people=$person_name.

query_var=falseвідключить ці варіанти, але ви все одно зможете отримувати пости за допомогою явного запиту WP_Query, наприклад:

new WP_Query( [ 'taxonomy'=>'people', 'term'=>$person_name ] )

За замовчуванням $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


meta_box_sanitize_cb
(callable)
Коллбек функція для очищення даних таксономії, збережених з метабоксу. Якщо не встановлено, то функція буде взята ґрунтуючись на значенні
$meta_box_cb .

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


default_term
(рядок/масив) (з WP 5.5)

Термін, який встановлюватиметься за умовчанням (якщо для запису не встановлено жодного терміну таксономії).

ID такого терміна зберігається в опції default_term_{$taxonomy_name}.

Можна вказати масив, щоб термін було створено, якщо його немає на сайті, див wp_insert_term() . Можливі ключі масиву:

  • name (рядок) – Ім’я дефолтного терміна.
  • slug (рядок) – Ярлик (склад) дефолтного терміна.
  • description (рядок) – Опис для дефолтного терміна.

_builtin
(логічний) (не для звичайного використання)
Параметр призначений для розробників. Якщо переключити на true, то це означатиме, що ця таксономія відноситься до внутрішньої таксономії WordPress і не є (кастомною).


Типово: false

Приклади

1

#1 Реєстрація таксономій

Приклад реєстрації двох таксономій “genres” та “writers” для постів типу “book”. Цей код можна вставити до файлу теми functions.php. Деякі аргументи розраховані на версію 3.1+:

//Хук, через який підключається функція
// реєструє нові таксономії (create_book_taxonomies)
add_action( 'init', 'create_book_taxonomies');

// функція, що створює дві нові таксономії "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
	));
}
0

#2 Додавання таксономії до ЧПУ

Дивіться приклади до описів функцій: WP_Rewrite

0

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

Код нижче, вказує як перейменувати наявну таксономію категорії (рубрики).

## Перейменуємо таксономію 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_Taxonomy[]. $wp_taxonomies Registered taxonomies.

список змін

З версії 2.3.0Введено.
З версії 4.2.0Introduced show_in_quick_edit argument.
З версії 4.4.0The show_ui argument is now enforced on the term editing screen.
З версії 4.4.0Public argument now controls whether taxonomy can be queried on the front end.
З версії 4.5.0Introduced publicly_queryable argument.
З версії 4.7.0Introduced show_in_rest , ‘rest_base’ і ‘rest_controller_class’ arguments для реєстрації taxonomy в API REST.
З версії 5.1.0Introduced meta_box_sanitize_cb argument.
З версії 5.4.0Added the registered taxonomy object as a return value.
З версії 5.5.0Introduced argument default_term .
З версії 5.9.0Introduced rest_namespace argument.

Код register_taxonomy() WP 6.0.2

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();

	//Add default term.
	if ( ! empty( $taxonomy_object->default_term ) ) {
		$term = term_exists( $taxonomy_object->default_term['name'], $taxonomy );
		if ($term) {
			update_option( 'default_term_' . $taxonomy_object->name, $term['term_id'] );
		} else {
			$term = wp_insert_term(
				$taxonomy_object->default_term['name'],
				$taxonomy,
				array(
					'slug' => sanitize_title( $taxonomy_object->default_term['slug'] ),
					'description' => $taxonomy_object->default_term['description'],
				)
			);

			// Update `term_id` in options.
			if ( ! is_wp_error( $term ) ) {
				update_option( 'default_term_' . $taxonomy_object->name, $term['term_id'] );
			}
		}
	}

	/**
	 * Fires по taxonomy is registered.
	 *
	 * @ Since 3.3.0
	 *
	 * @param string $taxonomy Taxonomy slug.
	 * @param array|string $object_type Object type або array of object types.
	 * @param array $args Array of taxonomy registration arguments.
	 */
	do_action( 'registered_taxonomy', $taxonomy, $object_type, (array) $taxonomy_object );

	/**
	 * Fires після конкретної taxonomy is registered.
	 *
	 * Динамічна порція файлового імені, `$taxonomy`, refers to the taxonomy key.
	 *
	 * Possible hook names include:
	 *
	 * - `registered_taxonomy_category`
	 * - `registered_taxonomy_post_tag`
	 *
	 * @ Since 6.0.0
	 *
	 * @param string $taxonomy Taxonomy slug.
	 * @param array|string $object_type Object type або array of object types.
	 * @param array $args Array of taxonomy registration arguments.
	 */
	do_action( "registered_taxonomy_{$taxonomy}", $taxonomy, $object_type, (array) $taxonomy_object );

	return $taxonomy_object;
}

Залишити відповідь

Ваша e-mail адреса не оприлюднюватиметься. Обов’язкові поля позначені *