Post Relationships API

Toolset Types provides a Post Relationship API allowing you to use custom PHP for querying related content in a convenient way. This page explains how to use this API and provides code examples.

toolset_association_created

Description

This action is executed just after creating a new association between two posts. Action will be executed when creating a new related content or connecting to an existing one.

Arguments
  • $relationship_slug. string: Relationship slug.

  • $parent_id. int: Post ID of the parent element of the relationship.

  • $child_id. int: Post ID of the child element of the relationship.

  • $intermediary_id. int: Post ID of the intermediary element of the relationship.

  • $association_id. int: ID of the new association created.

Output

More Usage examples

Example
// Refreshing WP Super Cache cache for both parent and child posts, in case you have views displaying related content.
add_action( 'toolset_association_created', 'refresh_cache_after_association_created', 10, 5 );
function handle_association_created( $association_slug, $parent_id, $child_id, $intermediary_id, $association_id ) {
    wpsc_delete_post_cache( $parent_id );
    wpsc_delete_post_cache( $child_id );
}

toolset_before_association_delete

Description

This action is executed just before deleting a new association between two posts.

Arguments
  • $relationship_slug. string: Relationship slug.

  • $parent_id. int: Post ID of the parent element of the relationship.

  • $child_id. int: Post ID of the child element of the relationship.

  • $intermediary_id. int: Post ID of the intermediary element of the relationship.

  • $association_id. int: ID of the new association created.

Output

More Usage examples

Example
// Refreshing WP Super Cache cache for both parent and child posts, in case you have views displaying related content.
add_action( 'toolset_association_created', 'refresh_cache_after_association_created', 10, 5 );
function handle_association_created( $association_slug, $parent_id, $child_id, $intermediary_id, $association_id ) {
    wpsc_delete_post_cache( $parent_id );
    wpsc_delete_post_cache( $child_id );

toolset_connect_posts

Description
Connects posts within a given post relationship.
Arguments
  • $relationship - string or array of strings Slug of the relationship or an array with the parent and the child post type of a legacy relationship.
  • $parent - integer Post ID of the parent post to connect
  • $child - integer Post ID of the child post to connect
Output
Returns true or false. On success, also outputs the ID of the created "intermediary_post" (zero is output if none was created).

More Usage examples

Example
// Connect a custom Author post with the ID of "5" to a custom Book post with the ID of "7" in a post relationship between Books and Authors
toolset_connect_posts( 'book-author', 5, 7 );

toolset_disconnect_posts

Description
Disconnects posts within a given post relationship.
Arguments
  • $relationship - string or array of strings Slug of the relationship or an array with the parent and the child post type of a legacy relationship.
  • $parent - integer Post ID of the parent post to connect.
  • $child - integer Post ID of the child post to connect.
Output
Returns true or false.

More Usage examples

Example
// Disconnect a custom Author post with the ID of "5" from a custom Book post with the ID of "7" in a post relationship between Books and Authors
toolset_disconnect_posts( 'book-author', 5, 7 );

toolset_get_parent_post_by_type

Description
Retrieves an ID of the parent post, using a legacy post relationship. Or, if new post relationships are already enabled, relationships migrated from the legacy implementation. For this to work, there needs to be a relationship between $target_type and the provided post’s type. Note: For more complex cases, use toolset_get_related_post() or toolset_get_related_posts() functions.
Arguments
  • $post - WP_Post|int Post whose parent should be returned.
  • $target_type - string Parent post type.
Output
int – Post ID or zero if no related post was found.

More Usage examples

Example
$book = get_post( $book_id ); $writer = toolset_get_parent_post_by_type( $book, 'writer' );

toolset_get_related_post

Description
Retrieve an ID of a single related post. Note: For more complex cases, use toolset_get_related_posts
Arguments
  • $post - WP_Post|int Post whose related post should be returned.
  • $relationship - string|string[] Slug of the relationship to query by or an array with the parent and the child post type. The array variant can be used only for legacy relationships (or those migrated from the legacy implementation, after new post relationships are enabled). The relationship slug variant will obviously work only if new post relationships are already enabled.
  • $role_name_to_return - string Which posts from the relationship should be returned. Accepted values are ‘parent’ and ‘child’. The relationship needs to have only one possible result in this role, otherwise an exception will be thrown. Defaults to ‘parent’.
  • args array - Additional query arguments. Accepted arguments:
    • meta_key, meta_value and meta_compare: Works exactly like in WP_Query. Only limited values are supported for meta_compare ('=' | 'LIKE').
    • s: Text search in the posts.
  • post_status: Array of post status values, or a string with one or more statuses separated by commas. The passed statuses need to be among the values returned by get_post_statuses() or added by the toolset_accepted_post_statuses_for_api filter. If this argument is not empty, only post with matching status will be returned.
Output
int – Post ID or zero if no related post was found.

More Usage examples

Example
$writer = toolset_get_related_post( $book_id, array( 'writer', 'book' ) );

toolset_get_related_post_types

Description
Get post types related to the provided one.
Arguments
  • string $return_role - Role that the results have in a relationship.
  • string $for_post_type - Post type slug in the opposite role.
Output
string[][] - An associative array where each post type has one key, and its value is an array of relationship slugs (in m2m) / post type pairs (in legacy implementation) that have matched the query.

More Usage examples

Example
// If there is a relationship appointment between "Doctor" and "Patient" post types we use the following
toolset_get_related_post_types( 'parent', 'patient' )
// This will return array( 'doctor' => array( 'appointment' ) )

toolset_get_relationship

Description
Get extended information about a single relationship definition.
Arguments
  • $identification - Relationship slug or a pair of post type slugs identifying a legacy relationship.
Output
array|null - Relationship information or null if it doesn't exist. The relationship array contains following elements:
Elements of the relationhship array
array(
    'slug' (only if m2m is enabled) => Unique slug identifying the relationship.
    'labels' (only if m2m is enabled) => array(
        'plural' => Plural display name of the relationship.
        'singular' => Singular display name of the relationship.
    ),
    'roles' => array(
        'parent' => array(
            'domain' => Domain of parent elements. Currently, only 'posts' is supported.
            'types' => Array of (post) types involved in a single relationship. Currently,
 there's always only a single post type, but that may change in the future.
        ),
        'child' => Analogic to the parent role information.
        'intermediary' (present only if m2m is enabled and if the relationship 
		is of the many-to-many type) 
		=> Analogic to the parent role information. The domain is always 'posts' and
there is always a single post type.
    ),
    'cardinality' => array(
        'type' => 'many-to-many'|'one-to-many'|'one-to-one',
        'limits' => array(
            'parent' => array(
                'min' => The minimal amount of connected parent ("left side") posts for
each child ("right side") post. Currently, this is always 0, 
but it may change in the future.
                'max' => The maximal amount of connected parent posts for each child
post. If there is no limit, it's represented by the value -1.
            ),
            'child' => Analogic to the parent role information.
        )
    ),
    'origin' => 'post_reference_field'|'repeatable_group'|'standard' 
How was the relationship created. "standard" is the standard one.
)

More Usage examples

Example
$relationship = toolset_get_relationship('tracks-of-an-album');