Taxonomy

Intro

Taxonomies in WordPress are ways to categorize posts from post types. WordPress comes with a couple of built-in taxonomies: (Categories, which are a hierarchical taxonomy and Tags, which are a non-hierarchical taxonomy). You can also register Custom Taxonomies for any post type.

The Taxonomy location allows you to associate containers with taxonomy creation and editing screens.

Usage through the interface

To add fields to a taxonomy with the the Administration Interface, please follow these steps:

1. If you are not on the "Add Container" screen already, locate the "Ultimate Fields" section in the administration area and click the "Add New" button on the top (next to the "Containers" title).
2. Locate the "Locations" box.
3. Click "Taxonomy" from the bottom row.
4. Select whether you want to display fields for a particular term, or you want to select rules manually in order to display the fields for all terms, matching a certain criteria.
5. Adjust all other needed options. All of them are described further down this page.

Usage through PHP

The taxonomy location in Ultimate Fields is handled by the Ultimate_Fields\Location\Taxonomy class. In order to use it, you can either create the new location object manually or let the container do it for you.

The constructor of the class looks like this:

public function __construct( $taxonomy = array(), $args = array() ) {

• $taxonomy is optional, but recommended. You can either pass a single taxonomy's slug as a string, or an array of taxonomy slugs.
• $args is an array, which allows you to set arguments without having to explicitly call the particular setter. For example, you can pass 'levels' => 1 instead of calling ->set_levels( 1 )

Manual creation

Create a new location by using the new keyword and assign it to the container through the add_location() method.

use Ultimate_Fields\Container;
use Ultimate_Fields\Location\Taxonomy;

$container = Container::create( 'category-settings' );

// Create a new location and add definitions to it
$location = new Taxonomy( 'category' );
$location->set_levels( 1 );

// Once the location has been fully set up, add it to the container
$container->add_location( $location );

Do not forget to use the correct namespace for the location class!

Automatic creation

You can also let the container create the location for you by providing the "taxonomy" string as the first parameter to add_location(). The rest of the parameters are the same as for the constructor of the location class.

use Ultimate_Fields\Container;

Container::create( 'category-settings' )
	->add_location( 'taxonomy', 'category', array(
		'levels' => 1
	));

This method allows you to use method chaining and shortens the syntax, in order to make the code more readable.

Data retrival

To retrieve the values of fields, associated with the Taxonomy location, $type parameter of all *_value functions should have the "term_XX" format with XX representing the ID of the term. You could also replace term with the particular taxonomy (ex. category), but normally your code is more readable when simply using the term keyword.

Examples:

<?php
$style = '';

if( get_value( 'category_color', 'term_3' ) ) {
  $style = "background-color: " . get_value( 'category_color', 'term_3' );
}
?>

<h2 style="<?php echo $style ?>"><?php the_title() ?></h2>

Options

There are a few options for the Taxonomy location and all of them are listed below.

Taxonomies

A single container can be associated with one or more taxonomies.

In the UI

use the checkboxes in the "Taxonomy" field of the location.

In PHP

you can use the the first parameter when creating the location or the add_taxonomy method later:

use Ultimate_Fields\Location\Taxonomy;

// Provide during initialization
$container->add_location( 'taxonomy', 'category' );

// Use the `add_taxonomy` method
$location = new Taxonomy();
$location->add_taxonomy( 'category' );
$container->add_location( $location );

Levels

WordPress supports two types of taxonomies:

• Hierarchical taxonomies, like categories, allow you to choose a parent term (parent category).
• Non-hierarchical taxonomies, like tags, do not support parents.

If you are using the Taxonomy location with a hierarchical taxonomy, you can specify which levels to show fields on:

1. Level 1 is a top-level term, which does not have a parent
2. Level 2 is a term, whose parent term is a top-level term
3. etc.

In the UI

You will automatically see a Levels field once you have selected a hierarchical taxonomy. You can enter levels, separated by commas in both the "Show on" and "Hide on" columns.

Levels are an MVIE Rule

You can add multiple values and/or exclude values by appending a minus sign in front of them.

Learn more

in PHP

You can use the levels argument or the set_levels method:

use Ultimate_Fields\Location\Taxonomy;

// Show on the second and third level
$container->add_location( 'taxonomy', 'category', array(
	'levels' => array( 2, 3 )
));

// Show on all levels but the first one
$location = new Taxonomy( 'category' );
$location->set_levels( -1 );
$container->add_location( $location );

Working with specific terms

If you prefer to, you can associate the Location taxonomy with particular terms. Supported are:

• Terms based on their IDs or slug. So you can either use 'uncategorized' or 1.
• Particular terms, as well as parents. So you can either work with a term or its children.

In the UI,

select "Show the container based on a particular term(s)" in the Location type field. This will allow you to choose particular terms and whether you want them to be the terms you are working with or their parents.

Terms and parents are an MVIE Rule

You can add multiple values and/or exclude values by appending a minus sign in front of them.

Learn more

In PHP

You can use the terms and parents arguments int he $args array or the set_terms and set_parents methods.

<?php
use Ultimate_Fields\Location\Taxonomy;

// Show on particular terms
$container->add_location( 'taxonomy', 'category', array(
	'terms' => array( 2, 3 )
));

$location = new Taxonomy( 'category' );
$location->set_terms( array( 2, 3 ) );
$container->add_location( $location );

// Show based on parents
$container->add_location( 'taxonomy', 'category', array(
	'parents' => array( 2, 3 )
));

// Show on all levels but the first one
$location = new Taxonomy( 'category' );
$location->set_parents( -1 );
$container->add_location( $location );

Adding to the customizer

Ultimate FIelds can display containers as sections in the Customizer for various locations and the Taxonomy location is one of them.

Please read the Adding fields to the Customizer article in order to learn how to display taxonomy fields in the cutomizer and to use their values afterwards.

Usage with the REST API

In the UI

you need to go the "REST API" tab and select which fields you want to include. You can also select if those fields are editable or not.

In PHP

Please read the REST API section section of the Container Settings article, as the REST functionality is directly controlled in containers.

Administration columns

The Taxonomy location supports Administration Columns. Click the link to learn how to use them.