Summer Sale! Use the coupon code WORDPRESS and save 30% OFF! Buy Now

Menu
Freebies, WordPress Plugins

Custom Post Types Relationships

Last Updated On

Custom Posts Types Relationships is a WordPress plugin that allows you to define relationships between posts in a manual way. This second version of the plugin now supports posts, pages and custom posts types, as well as allow you to define cross-type relationships. Sure, plugins that automatically get the job done are nice, but cat take you that far as they might link to irrelevant posts or change the output as more posts are added.

This version, renamed, is work based on Gerasimos’ original plugin, Custom Post Relationships, but extended to support custom post types, pages, a shortcode, a theme function, and an admin panel.

Download

You can download the CPTR plugin from our server, or visit the WordPress plugin directory page.

Installation

To install the plugin, you follow the same steps as with any other plugin. You download the plugin to your hard drive, unzip the archive and upload the resulting folder along with all files into the wp-content/plugins directory of your WordPress installation. You may also upload the zip file directly into the wp-content/plugins directory and extract it there using CPanel or whatever tools your host provides. Don’t forget to delete the zip file from your server once extracted. You may now activate the Custom Post Types Relationships plugin from the Plugins admin panel.

WARNING: In order for the thumbnail to be displayed, your theme must support post thumbnails. If it doesn’t, check that the add_theme_support( 'post-thumbnails' ) declaration is in your theme’s functions.php file and add it if necessary. The plugin should work fine without it though, it just won’t show any pictures.

Defining post relationships

Once the plugin is activated, a new box named Custom Post Types Relationships (CPTR) will appear at the bottom of the post editing screen (it will actually on post, page and custom post type editing screens). Depending on the configuration of your WordPress and/or your theme, this box may be shown under the main post editor, at the very bottom of the page, or anywhere in between.

The plugin’s interface is pretty simple, but for completeness sake I’ll include a few screenshots. A picture is worth a thousand words, right?

Configuring the plugin

To configure the default behavior of the CPTR plugin, navigate on your WordPress’ back-end, and under the Settings menu select the Custom Post Types Relationships sub-item.

There, you can set default values for all parameters, namely:

  1. The maximum number of items to display.
  2. Whether to show the excerpt.
  3. The maximum number of words that the excerpt should be.
  4. Whether to display the post’s thumbnail.
  5. The width and height of the post’s thumbnail.

Showing your relationships

The plugin supports a shortcode that can be used in individual posts and pages, as well as a function call that can be used more permanently within the themes. Both the function call and the shortcode, support the same features, although the shortcode does not require a particular order for the supported parameters. There is also a function that just returns the related posts, and then it’s up to you to implement your display logic, exactly the way you want it.

We purposely left out the ability to have a permanent heading showing up before the list of links, so that you can have total control over the output. Don’t want a heading? Don’t write one. Want one? Write it then. Too much of a hassle to always write a heading in each post? Use the theme function!

The easy, amateur or occasional way

So, you’ve written excellent copy, and you want to link it to more excellent copy. How to do it? You just type [cptr] in whatever place in your post you want them to show up. Easy, right? Just remember to write a title, heading or whatever before using the shortcode, so that people will know what they are reading.

The simplest way of using the shortcode is by typing anywhere in your post [cptr]. This will display the list of the related posts using the defaults as defined in the plugin’s admin panel.
If you want to override any of the defaults, you can do it by passing parameters to the shortcode. For example, if you want to show the excerpt you should type [cptr excerpt=1] or if you want to hide it you should type [cptr excerpt=0].

This is a list of all supported parameters that can be used with the shortcode. All parameters are optional.

  1. limit – Max number of relationships to show. 0 means unlimited. E.g. [cptr limit=5]
  2. excerpt – Shows or hides the excerpt. 1 means show, 0 means hide. E.g. [cptr excerpt=1]
  3. words – Max number of words in the excerpt. Default is 55. E.g. [cptr words=10]
  4. thumb – Shows or hides the post thumbnail. 1 means show, 0 means hide. E.g. [cptr thumb=1]
  5. width – Max width of thumbnail in pixels. Needs height to be set as well. E.g. [cptr width=300 height=200]
  6. height – Max height of thumbnail in pixels. Needs width to be set as well. E.g. [cptr width=300 height=200]

Of course, you can mix and match the attributes, so it’s perfectly fine to have a shortcode like this: [cptr thumb=1 words=40 excerpt=1 limit=10]

The hard, pro, permanent way

So, you want to integrate the CPTR plugin with the theme you are using or developing. For that, you can use the cptr() function call within your theme.

Like any PHP function with default parameters, all parameters of the cptr() function are optional but you have to follow a few rules. Have a look at the PHP documentation regarding default parameters, if you don’t know what I’m talking about.

All parameters to the function call are optional, but if set, they follow the default parameter rules of PHP. If you want to define some of the parameters but not a few preceding ones, you can pass a null value to that parameters, and it will use the default set in the plugin’s admin panel. The function’s signature is:
function cptr($echo=null, $limit=null, $excerpt=null, $words=null, $thumb=null, $width=null, $height=null)

Let’s examine the parameters:

  1. $echo – Boolean. When true it echoes the list and when false it returns it. Default is true.
  2. $limit – Integer. When 0 shows all relations. Any positive integer limits the number of relations. Default is 0.
  3. $excerpt – Boolean. When true it shows the excerpt and when false it hides it. Default is false.
  4. $words – Integer. Limits the number of words in the excerpt. Default is 55.
  5. $thumb – Boolean. When true it show the post’s thumbnail, and when false it hides it. Default is false.
  6. $width – Integer. The width of the thumbnail in pixels. Needs the height to be set as well. Default is 100.
  7. $height – Integer. The height of the thumbnail in pixels. Needs the width to be set as well. Default is 100.

So, for example, if you wanted all the default options, you would just call:
cptr();

If you wanted to return a max of 3 relations you would call:
cptr(false, 3);

And if you wanted everything to be default, but display the thumb, you would call:
cptr(null, null, null, null, true);

Implementing Custom Display Logic

So you don’t care about shortcodes and ease of use. You want to do something extraordinary with your theme, but you wish there was a way to get all the related items of that post. Wish no more, cptr_populate($postID) is here for you.

cptr_populate() accepts one parameter, the post ID of the post you want to retrieve the related items for, and returns an array of post objects. If no related posts are defined, an empty array is returned.

Displaying simple bits of info

The following example, coded into single.php will display a simple list of the titles of the related posts.

global $post;
$related = cptr_populate( $post->ID );
foreach ( $related as $item )
{
	echo "<p>" . $item->post_title . "</p>";
}

A full list of the available object properties that can be used, is given in the WordPress Codex.

Using template tags

The following example prints a simple list of titles linked to their posts, showing how you can use template tags in your code, such as the_title() and get_the_title(), the_permalink() and get_permalink(), etc.

global $post;
$original_post = $post;
$related = cptr_populate($post->ID);
foreach ( $related as $post )
{
	setup_postdata($post);
	echo '<p><a href="' . get_permalink() . '">' . get_the_title() . '</a></p>';
}
$post = $original_post;
setup_postdata($post);

Notice that because we overwrite the $post object when we use setup_postdata() within the foreach loop, we must keep a backup of it beforehand, hence the $original_post = $post; and restore it when we are finished, as done on the last 2 lines.

Conclusion

We take pride on our little plugin. Do you think it’s useful? We definitely think so. Is there any room for improvement? Let us know in the comments, and show us where and how you use it.

Download – Changelog

  • version 2.4 (7/Jan/2012)
    • Fixed a bug where the normal post object was not restored after the execution of cptr_category_selector(), when selecting related posts. (Thanks Pascal Rosin).
  • version 2.3 (14/Nov/2011)
    • Fixed a bug where the relations outputted wrongly by the shortcode.
  • version 2.2 (8/Nov/2011)
    • All functions/pages/settings etc that included the acronym CPT have been renamed to CPTR. Functions have been deprecated and will be available until v3.0.
    • Implemented automatic upgrade of settings etc for earlier version users.
  • version 2.1 (18/Feb/2011)
    • Version number changed to match the plugin repo.
    • Fixed a bug where the last related post was the current for $post after the plugin run.
    • Thumbnail now links to the post too.
    • The cpr_populate() function now always returns an array, even if empty.
  • version 1.0 (08/Oct/2010)
    • Initial release

Recent Posts

Join our Facebook Group
× Close Menu
Back to top