Taxonomy

Edit this page on Github

Overview

The taxonomy field allows you to select one or multiple taxonomy terms. This field has several settings that can be displayed as a: simple select dropdown, checkbox list, or beautiful select dropdown with select2 library.

If the taxonomy is hierarchical, you are able to display the field as a select or checkbox tree, e.g. show childen terms when parent term is selected.

Screenshots

Beautiful select with select2 library (default):

Checkbox list:

Checkbox tree:

Radio list:

Radio list inline:

Select tree:

Settings

Besides the common settings, this field has the following specific settings:

Name	Description
taxonomy	Taxonomy slug(s). Can be string for single taxonomy or array for taxonomies. Required.
query_args	Query arguments for getting taxonomy terms. Uses same arguments as get_terms(). Optional.
placeholder	The placeholder for the select box. Default is “Select a {taxonomy label}”. Applied only when the field_type is a select field.
add_new	Allow users to create a new term when submitting the post (true or false). Added in v4.18.0.
remove_default	Remove the default WordPress taxonomy meta box. Added in v4.18.3.
field_type	How the terms are displayed? See below.

This field inherits the look and field (and settings) from other fields, depending on the field_type, which accepts the following value:

Field type	Description	Settings inherited from
select	Simple select dropdown.	select
select_advanced	Beautiful select dropdown using the select2 library. This is the default value.	select_advanced
select_tree	Hierachical list of select boxes which allows to select multiple items (select/deselect parent item will show/hide child items). Applied only when the taxonomy type is hierarchical (like pages).	select
checkbox_list	Flatten list of checkboxes which allows to select multiple items.	checkbox_list
checkbox_tree	Hierachical list of checkboxes which allows to select multiple items (select/deselect parent item will show/hide child items). Applied only when the taxonomy type is hierarchical (like pages).	checkbox_list
radio_list	Flatten list of radio boxes which allows to select only 1 item.	radio

Note that for select_tree, checkbox_list, checkbox_tree, the multiple setting is always set to true.

Sample code

This code shows pages in select2 dropdown:

array(
    'name'       => 'Taxonomy',
    'id'         => 'taxonomy',
    'type'       => 'taxonomy',

    // Taxonomy slug.
    'taxonomy'   => 'category',

    // How to show taxonomy.
    'field_type' => 'select_advanced',
),

The code below shows pages in a checkbox tree format:

array(
    'name'       => 'Taxonomy',
    'id'         => 'taxonomy',
    'type'       => 'taxonomy',

    // Taxonomy slug.
    'taxonomy'   => 'category',

    // How to show taxonomy.
    'field_type' => 'checkbox_tree',
),

Ajax Load

Since version 5.2, Meta Box uses Ajax to increase the performance for the field query. Instead of fetching all terms at once, the plugin now fetches only some terms when the page is loaded, and then fetches more terms when users scroll down to the list.

See this video for demonstration (made for posts, but works similar for taxonomies):

This feature is available only for fields that set field_type to select_advanced. There are some extra parameters for you to disable or customize it.

Enable/Disable Ajax Requests

To enable the Ajax requests, simply add 'ajax' => true (which is added by default) to the field:

array(
    'id' => 'project_cat',
    'title' => 'Project Categories',
    'type' => 'taxonomy',
    'taxonomy' => 'project_cat',
    'ajax' => true, // THIS
),

Setting this parameter to false will disable Ajax requests, making it work exactly the same as in previous versions.

Limit The Number of Terms for Pagination

Similar to the previous version, the number of terms for pagination is set via the number in the query_args parameter:

array(
    'id' => 'project_cat',
    'title' => 'Project Categories',
    'type' => 'taxonomy',
    'taxonomy' => 'project_cat',
    'ajax' => true,
    'query_args' => array(
        'number' => 10, // THIS
    ),
),

Unlike in previous versions, this number is used only for Ajax requests to fetch the next bunch of terms. The new fetched terms will be appended to the list of options in the dropdown, to make the infinite scroll effect.

It also doesn’t affect the initial load of the field. When the field is loaded, Meta Box only queries for saved terms (which is usually not many). So the initial query is very minimal and doesn’t cause any performance problem.

Searching Parameters

You probably don’t want to perform an Ajax request when open the dropdown at first. You might want to make Ajax requests only when users type something and search for that. To do that, you need to set the minimumInputLengthfor the input, as below:

array(
    'id' => 'project_cat',
    'title' => 'Project Categories',
    'type' => 'taxonomy',
    'taxonomy' => 'project_cat',
    'ajax' => true,
    'query_args' => array(
        'number' => 10, // THIS
    ),
    'js_options' => array(
        'minimumInputLength' => 1, // THIS
    ),
),

This parameter sets the minimum number of characters required to start a search. It may be good if you don’t want users to make too many Ajax requests that could harm your server.

Data

This field does not save any value in the database. Instead of that, it sets the taxonomy terms for the current being edited post. In short, it behaves exactly like the “Category” and “Tags” meta boxes.

The purpose of this field is to replace the default WordPress meta box for taxonomy and offer more options to control how it displays.

For this reason, if you have 2 taxonomy field, and select different values for them, after saving, they still show the same value.

If you prefer saving data, check out taxonomy advanced.

Template usage

Getting value of this field can be done via the helper function:

$terms = rwmb_meta( $field_id );
if ( ! empty( $terms ) && ! is_wp_error( $terms ) ) {
    foreach ( $terms as $term ) {
        echo '<p>', $term->name, '</p>';
    }
}

If the field is neither cloneable or multiple, e.g. it has single value, then the rwmb_meta() function returns the single term object:

$term = rwmb_meta( $field_id );
echo '<p>', $term->name, '</p>';

The code above shows the term name only. If you want to show term link, use this code:

$term = rwmb_meta( 'pub_type_field' );
printf( '<a href="%s">%s</a>', get_term_link( $term ), $term->name );

If you just want to output selected terms in an unordered list, use this code:

rwmb_the_value( $field_id );

Read more about rwmb_meta() and rwmb_the_value().

Filters

rwmb_taxonomy_choice_label and rwmb_{$field_id}_choice_label

These filters allow developers to change the label of taxonomy fields. The 1st label applies to all taxonomy fields, and the later for a specific field.

Example: If you are using a field called my_field and you want to change the label in the select box, use this code:

function my_field_filter( $label, $field, $term ) {
    return $label . ' - Custom text';
}
add_filter( 'rwmb_my_field_choice_label', 'my_field_filter', 10, 3);

Edit this page on Github