Related Posts Plugin for MODX

Feb 26, 2012

MODX CMS now has an Extra to display a list of links to "related" blog posts - the getRelated snippet. It, and the bonus snippet used in this post, are both written by the prolific MODX developer Mark Hamstra of modmore - thanks Mark!!

What's It For?

One of the things (perhaps the thing) that makes blogging such a powerful content delivery tool, is the multitude of ways in which that content can be organized and displayed to visitors. You can sort blog posts by Categories, Tags, Archival Date, Latest Posts, and Related Posts, among others. Each listing option provides visitors with more reasons to explore the site, rather than leave (bounce). This generates more engagement, better metrics all round for the blog, and hopefully more revenue.

*UPDATE[2018/12]: 6-plus years later, the foregoing is not necessarily true anymore.

The MODX platform can do all of the above and a whole lot more. However, until recently MODX was missing an easy way to dynamically generate a list of Related Blog Posts. Enter: getRelated!

Resources

This tutorial is for those who already have a MODX based blog. If you don't - you should! Read the Official Documentation on Creating a Blog in MODX. Note: MODX Revolution 2.2 has a new blog engine addon called "Articles". However, getRelated - and this entire tutorial - will not work with Articles as of the time of writing. Also, I've only tested it with MODX 2.1.3 - but Mark is no slouch and I'd be very surprised if it didn't work on all versions of MODX Revolution. Check back for updates on all this.

Step-by-Step Installation Instructions

  1. Download and install the getRelated Extra via Package Management.
  2. Add the snippet call to one of your templates. The basic one is this: [[getRelated]] There, wasn't that easy?

Just like MODX, getRelated allows you the flexibility to easily customize how your content displays. For example, here's an example snippet call:

[[getRelated? 
    &parents=`12` 
    &parentsDepth=`2` 
    &fields=`introtext:4,pagetitle:3,tv.tags:2,description:1` 
    &hideContainers=`1` 
    &tplOuter=`outerTpl` 
    &tplRow=`rowTpl` 
    &limit=`5`
]]

Break it down:

  • &parents » Set the Resource ID of the document under which you want getRelated to search for related posts. In this example the parent container has the ID "12", but this can be a comma-delimited list of several containers.
  • &parentsDepth » The number of levels beneath the parent containers to search for related content. Keep this to the minimum that will retrieve useful results.
  • &fields » Customizes the algorithm used to identify related content. The syntax is name_of_field:weight separated by commas - the "weight" being how important that field is. In the example, introtext is the most important, and description is least.
  • &hideContainers » Hides container resources. The containers may be blog sections, for example, and not actual posts.
  • &tplOuter and &tplRow » These allow you to customize the output. I'll go into more detail about these below.
  • &limit » Limits the output to 5 items, so as not to blow up the page!

Snippet Templates & Placeholders

Here's what my "outerTpl" chunk looks like:

<h3>Related Posts</h3>  
<ul>[[+wrapper]]</ul>

Break it down:

  • <h3>Related Posts</h3> » Straightforward. I wanted to customize the header for the Related Posts listing. By default, it's a long heading likely intended for the main content area, whereas mine shows up in the sidebar.
  • [[+wrapper]] » This is where getRelated's output will go. The rest is the same as the default html template.

That was easy. Where that [[+wrapper]] placeholder is, getRelated will display content from the related posts, formatted based on the chunk specified in the snippet call, named "rowTpl":

<li>    
    <a href="[[~[[+id]]]]" title="[[+pagetitle]]">[[+pagetitle]]</a><br />
    <span> » in [[+parent:miniSnippet]]</span>
</li>

Break it down:

  • Everything in the anchor tag » The MODX ID placeholder generates a link to the related post, and renders the contents of the pagetitle field as the title attribute and the link text. Note the [[+ syntax instead of the usual [[* because this is a template used by a Snippet!
  • <span>» in [[+parent:miniSnippet]]</span> » This is where things get a tiny bit tricky. In the example, I used Mark's mini-snippet from his blog post here, in order to output some meta info about the related post, in this case the menutitle of the post's parent resource. This is because the parent Resources are categories, so we get this: "» in Category_Name" beneath each listing.

Now it wouldn't be fair unless I also shared with you Mark's mini-snippet code:

if ($input < 1) { 
    return ''; 
}  
$obj = $modx->getObject('modResource',array('id' => $input));  
return $obj->get('pagetitle');

We can replace ('pagetitle') with ('menutitle') to output the desired field. The Snippet is used as an output modifier in the above case in order to grab the menutitle of the parent.

*UPDATE: There are faster ways to get a single field from a MODX Resource programmatically. See what Bob says on the matter.

So there you have it! A nice little Related Posts Widget for your blog, or any other content. It would also work great on a news site, for example. Ya gotta love MODX and its vibrant community of generous Extras Developers...Hats Off To You!

modmore premium extras