WP Object

Purpose

The WP Object field is one of the most powerful fields in Ultimate Fields. It allows users to select an object from a variety of available types. It is also extended by the WP Objects Field, which allows the selection of multiple objects simultaneously.

Play Preview Video

You can set the Object field up to allow users to select amongst the most common data types in WordPress:

• Posts (with cusotmizable post types)
• Terms (with customizable taxonomies)
• Users

The chooser of the field allows editors to both search for a particular piece of content, as well as filter the results by:

• Particular post type and terms for posts
• Taxonomy for terms
• Roles for users

Additional filters can easily be added through the WordPress Plugin API.

Once an item has been selected, the user sees a preview of the item, which allows them to see details about it (post type, category, etc.), as well as an edit link, which allows quick navigation between related objects.

Options

The following options are available for both this field and the Objects field.

Types

In the interface you can select what types to enable through the "Object Types" field. Once you do so, you will see additional fields for post types and taxonomies to select.

In PHP, you should use the add method.

add( $type_slug, $args = array() )

It accepts the following parameters:

1. $type_slug should be a string object type. Out of the box UF supports "posts", "terms" and "users".
2. $args is an optional array with options for the particular type:
   • when $type is "posts", those are the same arguments that you would use for get_posts and WP_Query
   • when $type is "terms", those are the same arguments that you would use for get_terms, including taxonomy.
   • when $type is "users", those are the same arguments that you would use for get_users.

Ultimate Fields will automatically load all needed filters based on the arguments, which you provide to add. For example, if you include a post_type in the args when adding posts, Ultimate Fields will only include taxonomy filters, based on the particular post type.

You may not call add at all to enable all available types with their default settings. You may also call it multiple times with multiple types to enable all of them.

// This field will allow users to select from all available types
Field::create( 'wp_object', 'button_target' ),

// A field only for posts
Field::create( 'wp_object', 'related_article' )->add( 'posts', 'post_type=post' );

// A field only for terms
Field::create( 'wp_object', 'related_articles_category' )->add( 'terms', 'taxonomy=category' );

// A field only for users, without any additional arguments
Field::create( 'wp_object', 'photographer' )->add( 'users' );

// Allow multiple types to be selected
Field::create( 'wp_object', 'slide_object' )
	->add( 'posts', 'post_type=post' )
	->add( 'users' );

Hiding and showing filters

You can disable and enable filters in the chooser upon wish.

In the UI, simply check the "Hide Filters" checkbox in the "Appearance" section of the field.

In PHP you can use the hide_filters and show_filters methods:

Field::create( 'wp_object', 'related_post' )
	->add( 'posts', 'post_type=post' )
	->hide_filters()

Modifying filters

The chooser of the Object, Objects and Link fields allows you to modify the existing filters or add new ones by utilizing a couple of WordPress filters. Those filters allow you to change the options in the filter and to apply them in database calls.

/**
 * @param mixed[]          $filters The existing filters, in format $label => $options.
 * @param UF\Field\Object  $field   The field that is being modified.
 * @return mixed[]
 */
$filters = apply_filters( 'uf.object.filters', $filters, $this );

This filter receives the field and allows you to modify the options in the filter. Please keep in mind that at this point the filters are added to the field and will be shown as options, but will not be applied when selected.

/**
 * @param mixed[]                $args      The arguments that are already prepared.
 * @param UF\Field\Object        $field     The field that is loading data.
 * @param mixed[]                $selection The filters, search and pagination that are applied.
 * @param UF\Helper\Object\Type  $type      The type of items that is being loaded.
 * @return mixed[]
 */
$args = apply_filters( 'uf.object.<type_slug>.args', $args, $this, $filters, $type );

Once a user has choosen an options in the filter, here you can actually parse the option and update the arguments for the used function (get_posts and etc.).

Please read the Adding a filter to the Object field tutorial to see how to add a new filter to the Object field.

Button text

You can change the text of the "Select Item" button.

In the interface, use the "Button Text" field. Leaving it empty will fall back to "Select Item" as text.

In PHP you can use the set_button_text( $text ) method:

Field::create( 'wp_object', 'next_article' )
	->set_button_text( __( 'Select article', 'my_textdomain' ) )

Output Type

You can select various output types for the object field.

• The ID of the selected object (id)
• The title of the selected object (title)
• The URL of the selected object (url)
• A link to the selected object (link)

In the interface, use the field in the last tab (Output Settings) to select the needed output type. In PHP use the slug, listed above in combination with the set_output_type method:

Field::create( 'wp_object', 'next_item' )->set_output_type( 'title' )

Specifically for the link type, the field will use the title of the object for the link text. You can overwrite this through the Link Text field. In PHP you can use the set_link_text method:

Field::create( 'wp_object', 'next_item' )->set_output_type( 'link' )->set_link_text( 'Next article' )

Usage

<!-- Display the value of the field, using the specified format -->
<?php if( get_value( 'next_item' ) ): ?>
<p>
    Next article: <?php the_value( 'next_item' ) ?>
</p>
<?php endif ?>

<!-- Use the ID of an item -->
<?php
$item = get_value( 'next_item' );

if( is_a( $item, 'WP_Post' ) ) {
    echo $item->ID . ' of ' . $item->post_type;
} elseif( is_a( $item, 'WP_Term' ) ) {
    echo $item->term_id . ' of ' . $item->taxonomy;
} elseif( is_a( $item, 'WP_User' ) ) {
    echo $item->ID . ' of users';
}
?>