Actions and filters

p2p_connected_args

Called before querying for posts that are already connected to the current post.

p2p_connectable_args

Called before querying for posts that the user can connect to the current post.

Example 1: Ordering pages alphabetically

Given the 'posts_to_pages' connection type, say you want to display the candidate pages alphabetically instead of chronologically when creating connections.

You can do this with a little bit of PHP:

<?php
function order_pages_by_title( $args, $ctype, $post_id ) {
	if ( 'posts_to_pages' == $ctype->name && 'to' == $ctype->get_direction() ) {
		$args['orderby'] = 'title';
		$args['order'] = 'asc';
	}

	return $args;
}

add_filter( 'p2p_connectable_args', 'order_pages_by_title', 10, 3 );

Note that, since we check the direction, only pages will be affected by this change.

Example 2: Increasing the number of results per page

Posts-to-posts uses a custom query arg to determine how many results to show per page: p2p:per_page. To increase this from the default of 5 you can use a custom filter.

<?php
function connectable_results_per_page( $args, $ctype, $post_id ) {
    $args['p2p:per_page'] = 5;

    return $args;
}

add_filter( 'p2p_connectable_args', 'connectable_results_per_page', 10, 3 );

Note: Because we did not check the connection type, this would affect all admin boxes.

p2p_new_post_args

Called before creating a post via the "New" tab in the admin metabox.

Example: Create published pages

By default, when you create a page directly from the P2P admin box, it's status will be 'draft'. If you want it to be published immediately, you can do something like this:

<?php
function p2p_published_by_default( $args, $ctype, $post_id ) {
	if ( 'posts_to_pages' == $ctype->name && 'to' == $ctype->get_direction() ) {
		$args['post_status'] = 'publish';
	}

	return $args;
}

add_filter( 'p2p_new_post_args', 'p2p_published_by_default', 10, 3 );

p2p_admin_box_show

Example: Show the box only for pages with a certain template.

<?php
function restrict_p2p_box_display( $show, $ctype, $post ) {
	if ( 'posts_to_pages' == $ctype->name && 'to' == $ctype->get_direction() ) {
		return ( 'YOUR-TEMPLATE.php' == $post->page_template );
	}

	return $show;
}

add_filter( 'p2p_admin_box_show', 'restrict_p2p_box_display', 10, 3 );

p2p_candidate_title

Called when displaying posts or users in the admin metabox.

Example: Display a custom field value after each candidate's title.

<?php
function append_date_to_candidate_title( $title, $post, $ctype ) {
	if ( 'posts_to_pages' == $ctype->name && 'page' == $post->post_type ) {
		$title .= " (" . $post->_wp_page_template . ")";
	}

	return $title;
}

add_filter( 'p2p_candidate_title', 'append_date_to_candidate_title', 10, 3 );

p2p_created_connection

Right after a connection is created, the 'p2p_created_connection' action fires, passing the $p2p_id of the new connection.

Here's an example of how you could add an item to the BuddyPress activity stream each time a connection of a certain type is created:

<?php
function handle_new_connection( $p2p_id ) {
  $connection = p2p_get_connection( $p2p_id );

  if ( 'YOUR_CONNECTION_TYPE' == $connection->p2p_type ) {
    bp_activity_add( ... );
  }
}
add_action( 'p2p_created_connection', 'handle_new_connection' );

p2p_delete_connections

Right before one or more connections are deleted, the 'p2p_delete_connection' action fires, passing the list of $p2p_id of the connections to be deleted.

p2p_widget_html

p2p_shortcode_html

You can control the output of widgets and shortcodes with a pair of similar hooks. Here's an example of how you can make widgets and shortcodes use template files from your theme:

<?php
add_filter( 'p2p_widget_html', 'my_p2p_template_handling', 10, 4 );
add_filter( 'p2p_shortcode_html', 'my_p2p_template_handling', 10, 4 );

function my_p2p_template_handling( $html, $connected, $ctype, $mode ) {
	$template = locate_template( "p2p-{$mode}-{$ctype->name}.php" );

	if ( !$template )
		return $html;

	ob_start();

	$_post = $GLOBALS['post'];

	foreach ( $connected->items as $item ) {
		$GLOBALS['post'] = $item;

		load_template( $template, false );
	}

	$GLOBALS['post'] = $_post;

	return ob_get_clean();
}

That code could go in your theme's functions.php or in a custom plugin.

Now, say you have a posts_to_pages connection type and you've set up a widget for it. If you create a p2p-ul-posts_to_pages.php file in your theme, the widget will load that file to render the list of connected items.

Here's what that file might look like:

<div>
  <?php the_post_thumbnail(); ?>
  <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
</div>

The same will happen if you use a shortcode, such as [p2p_connected type=posts_to_pages mode=ul].