register_taxonomy()
Створює нову довільну таксономію WordPress. Дозволяє змінити існуючу таксономію.
Функція дозволяє додати (зареєструвати) користувальницьку таксономію WP або змінити дані таксономії, яка вже була зареєстрована.
При зміні існуючої таксономії значення параметра $object_type із початкової реєстрації буде перезаписано. Тому, його важливо вказати заново таке ж, як було або нове.
Таксономія – це можливість класифікувати об’єкти, наприклад рубрики для постів. Читайте докладніше про таксономію .
Не рекомендується викликати функцію до події init :
add_action('init', 'function_name');
Зарезервовані назви
У назві таксономії (параметр $taxonomy) або у параметрі query_var не можна використовувати зарезервовані імена WordPress. Наприклад, не можна вказувати author
.
Це особливо важливо, якщо ви передаєте назву через масив $_GET або $_POST. Це може призвести до того, що WordPress відповість помилкою 404 без будь-яких інших підказок.
Повний список зарезервованих назв (чорний список) , які не можна використовувати, як ім’я нової таксономії або параметри, що стосуються запиту.
Рекомендується спочатку реєструвати таксономію, а потім тип запису, з яким ця таксономія пов’язана!
Ця особливість у деяких випадках позбавить вас від багів та купи витраченого часу.
// правильний порядок реєстрації типу запису та її таксономії 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 Чи показувати таксономію в адмін-меню.
- true – таксономія буде показана як підменю типу запису, до якої вона прикріплена.
- false – підменю не буде показано.
Параметр $show_ui має бути включений (true).
За замовчуванням: якщо ні, то аргументу show_ui
-
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 для таксономій, приєднаних до інших об’єктів, наприклад, до користувачів.
Функція отримає такі параметри:
- $terms – term_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 Реєстрація таксономій
Приклад реєстрації двох таксономій “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 )); }
#2 Додавання таксономії до ЧПУ
Дивіться приклади до описів функцій: WP_Rewrite
#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.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 | Public argument now controls whether taxonomy can be queried on the front end. |
З версії 4.5.0 | Introduced publicly_queryable argument. |
З версії 4.7.0 | Introduced show_in_rest , ‘rest_base’ і ‘rest_controller_class’ arguments для реєстрації taxonomy в API REST. |
З версії 5.1.0 | Introduced meta_box_sanitize_cb argument. |
З версії 5.4.0 | Added the registered taxonomy object as a return value. |
З версії 5.5.0 | Introduced argument default_term . |
З версії 5.9.0 | Introduced rest_namespace argument. |