Taxonomy Advanced

Improve this page

Overview

The taxonomy advanced 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.

The taxonomy advanced field is very similar to taxonomy field. Both fields display terms to users to select. The only difference is how they store selected terms in the database:

  • taxonomy: doesn’t store any terms in the post meta. Instead, it sets post terms. Think about it like a replacement of Category or Tag meta box of WordPress.
  • taxonomy_advanced: store terms’ IDs in the post meta and doesn’t set post terms.

Screenshots

Beautiful select with select2 library (default):

taxonomy select

Checkbox list:

taxonomy checkbox list

Checkbox tree:

taxonomy checkbox tree

Radio list:

radio list

Radio list inline:

radio list inline

Select tree:

taxonomy select tree

Settings

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

Name Description
taxonomy Taxonomy slug. String. 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_advanced',

    // 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_advanced',

    // 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_advanced',
    '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_advanced',
    '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_advanced',
    '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

Unlike the taxonomy field, this field saves terms’ IDs in the database.

If field is not multiple, then a single term ID is saved in the database. Otherwise, the field saves multiple term IDs in a single row in the database in the comma separated strings (e.g. format 1,2,3).

If the field is cloneable, then the value is stored as a serialized array in a single row in the database.

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

Improve this page