Overview

The Relationship field creates a very attractive version of the post object field. With a Relationship field, you can select from pages + posts + custom post types. This field is useful for advanced linking to another page / post object.

Creating a Relationship field

The Relationship field contains options to customize your field:

  • Post type: You can filter the choices by selecting post types.
  • Filter from Taxonomy: You can filter the choices even more by selecting specific taxonomies / categories
  • Maximum Posts: You can set the maximum number of posts allowed to be selected. Leave this field blank or set to -1 for infinite selections.

Edit screen

Template usage

The API will return an array of post objects in the same way that the get_posts function would.

Basic loop (with setup_postdata)

This example shows how to load the selected posts from a relationship field and display them in a list. This example uses a function called setup_postdata which will override the global $post object and allow functions such as the_title to target the selected post. When using this function, it is important to reset the post after your loop. http://codex.wordpress.org/Template_Tags/get_posts#Reset_after_Postlists_with_offset

<?php 
 
$posts = get_field('relationship_field_name');
 
if( $posts ): ?>
    <ul>
    <?php foreach( $posts as $post): // variable must be called $post (IMPORTANT) ?>
        <?php setup_postdata($post); ?>
        <li>
            <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
            <span>Custom field from $post: <?php the_field('author'); ?></span>
        </li>
    <?php endforeach; ?>
    </ul>
    <?php wp_reset_postdata(); // IMPORTANT - reset the $post object so the rest of the page works correctly ?>
<?php endif; ?>

Basic loop (without setup_postdata)

This example shows how to load the selected posts from a relationship field and display them in a list. This example does not use the above mentioned setup_postdata function, instead, the $post->ID is passed to the functions to target the selected post. Please note that some of the function names change to allow for the $post_id parameter such as the_title() => get_the_title().

<?php 
 
$posts = get_field('relationship_field_name');
 
if( $posts ): ?>
	<ul>
	<?php foreach( $posts as $p ): // variable must NOT be called $post (IMPORTANT) ?>
	    <li>
	    	<a href="<?php echo get_permalink( $p->ID ); ?>"><?php echo get_the_title( $p->ID ); ?></a>
	    	<span>Custom field from $post: <?php the_field('author', $p->ID); ?></span>
	    </li>
	<?php endforeach; ?>
	</ul>
<?php endif; ?>

Using WP_Query arguments

It is possible to load only the selected post ID’s, instead of the post objects. This way, you can use the ID’s within a WP_Query and specify arguments such as posts_per_page, order and orderby. To learn more about the WP_Query arguments, please read http://codex.wordpress.org/Class_Reference/WP_Query#Parameters.

Note that the get_field function has 2 false parameters. The first param is for the $post_id and is not relevant, but the second one is to tell ACF not to format the value, and return only what is in the DB (array of IDs)

<?php 
 
// get only first 3 results
$ids = get_field('conference_talks', false, false);
 
$query = new WP_Query(array(
	'post_type'      	=> 'conferences',
	'posts_per_page'	=> 3,
	'post__in'		=> $ids,
	'post_status'		=> 'any',
	'orderby'        	=> 'rand',
));
 
?>

Reverse Query

It is possible to perform a reverse query on a post (post A) to find all the posts (post B, post C) which have selected it (post A). To learn more about a reverse query, please read this in-depth tutorial: http://www.advancedcustomfields.com/resources/tutorials/querying-relationship-fields/

Customization

The relationship field contains filters to allow for customization of the edit screen interface. To learn more, please read the following articles: