Have you ever had a client asking for showing a list of related articles or news items? Chances are you've applied a technique to show a list of all articles in a Template Variable, allowing the client to handpick the ones that are related. This is a great technique and I have written about it in the MODX Documentation, but the admin or editor still has to manually pick what is related. Surely there's an automated way as well?

Back in fall 2011 I was contacted by Vierkante Meter, a Dutch web agency focusing on accessible websites, with exactly that request: a way to automatically show related articles. Some time later getRelated was born as the answer to their questions as well as that of many other developers. I've even deployed it on my own site! Just look a the "Related Articles" block to the bottom right of this post (not visible on mobile for now).

getRelated is very powerful, but, if I can say so myself, still very easy to use. It can be installed via the MODX Package Manager and from there you just need to call the snippet in your template - and it's there! But of course, the power is in the details..

What makes getRelated awesome

(More information about the aspects mentioned below can of course be found in the getRelated Documentation.)

#1: Configurable algorithm.

getRelated checks out the resource it is called on (or the resource you specify with &resource=`ID`), and identifies unique words in the fields you specified, and it uses those to find matching resources. To come up with the order in which they are returned, it specifies a value for every field. A value of 5 means that every matching word in that field is rewarded with 5 points added to the total. At the end of the processing cycle it sorts the results by the amount of points rewarded.

By default it only looks at the pagetitle and introtext, but by simply specifying the &fields property you can tell it what fields to use and how valuable they are. According to the docs:

That's a lot of information in only a few lines, but it tells you how to define the value of each field, and that you can even use TVs for them. To show how that works, here's the &fields property used on my site:

The most value is assigned to the "mh.categories" template variable: it's what I use to categorize my posts in 2 or 3 categories each, such as front end development or ExtJS. The "12" means that every category is worth 12 points when it matches on a different resource. So if another article has one category in common it scored 12 points. Every matching word in the pagetitle is worth 6 points, longtitle gets 4 points per matched word and the introtext gives 2 points. By defining all of that in the &fields property you can pretty much define your own algorithm for finding related pages automatically. You may use both categories and tags, so you could give categories a higher value compared to the tags to get the most accurate results.

#2: Completely configurable output

Besides the ability to specify, you are able of completely configuring how your related resource is shown. The default is a h3 tag and an unordered list with the top 3 related resources. But using the &tplOuter and &tplRow property you can change it to your hearts content. 

As performance is a big priority with a tool like this, it only sets placeholders for the fields you specified, and as of the 1.1 release (for MODX 2.1+) it also allows you to use TVs in the output. Just specify the resource fields (ie pagetitle, introtext) in the &returnFields property and the TV names in &returnTVs. Again, for speed it only gets the TVs for the top ranking results, so no performance is lost. 

For example, this is a screenshot from a current project (a jewellery webshop) of mine, which uses getRelated with returnTVs to show related articles. 

And the getRelated snippet call:

The match is completely defined on TVs used for products: the tagline, colors, materials and stones. Here's the getrelated.row chunk:

The getFirstImage custom snippet is used to get the first image: the product.images TV uses MIGX to allow unlimited amount of images. The custom snippet uses the following chunk to show the image (product.firstname chunk):

#3: Excited client!

#4, #5, #6 etc: More possibilities!

Use the &parents, &includeHidden, &hideContainers, &contexts, &exclude and more properties to decide which resources to include or not. 

Spotted in the wild!

We've just hit 650 downloads (well, okay: 647, but close enough!) of getRelated so far, I am very interested in seeing how people have been using it! Feel free to leave a link in the comments to show how you're applying it... I may feature the most impressive uses here as well!

Read 11 comments and share your own thoughts!

Since the launch of MODX Revolution 2.2pl, the use of the Articles blogging tool has been growing exponentially as well. This post walks you through a question that is being asked several times per day: how do I show Articles on my homepage or in a sidebar?

Including Articles in Wayfinder or getResources

As individual articles are stored and used just like any other resource, you can use the same tools to display them such as getResources or Wayfinder. The trick there is that Articles are set as hidden from menus, which both of these snippets hide by default. Luckily both of the mentioned snippets support including those as well using a simple property, as shown below.

Wayfinder uses the &ignoreHidden property. As it is primarily a menu building tool, if you want it to to show hidden resources you tell it to ignore the hidden state. getResources is not linked with menus directly, and uses the &showHidden property to indicate you also want hidden resources to show up. So they do the same, but the terminology used for it is slightly different and can seem counter intuitive at first. 

But what if you don't want them included?

Excluding Articles in Wayfinder or getResources

If you don't want the articles posts to show up in a Wayfinder menu or getResources list, you can filter them out by checking against the "class_key" variable.

Normal resources have that set to modDocument (or modWebLink, modSymLink or modStaticResource), but as Articles installs a custom resource class the class_key is different as well. The blog container itself is an ArticlesContainer class, and the individual articles are of class Article. Knowing this, we can filter against this using the &where property. This &where property, commonly available in extras, accepts a json string representing an array (with xPDOQuery::where style comparisons). That may sound complicated, but here's an example for Wayfinder and getResources:

And that's all! Happy blogging!


Mere houres after publishing this article the MODX RTFM was updated with some more information on accessing all of the placeholders used in the Articles templates,  including the latest articles, tags and comments. Find it here.

Read 4 comments and share your own thoughts!

Monday at about 4.30 CET the hosting provider of my host got hacked at the root level which resulted in all of my websites going down, until manually being restored to an old backup Wednesday morning at about 4am CET. 

Just to clarify this before getting started.. while I purchase my hosting of Skytoaster, this specific server is run by AltusHost. If the following post is too long for your liking: I still recommend Skytoaster, just please do not, ever, trust a host that doesn't keep backups. And keep backups more often than I did.

What happened?

According to the official statement of AltusHost posted on Facebook, their version of WHMCS (which seems shady to say the least) a hacker gained root access to their billing panel and started removing servers, which lasted about 10 minutes. While they're statement says 5PM CET, I was working on a site on that server at around 4.30PM when it started showing connectivity issues, so my guess is that they've rounded up the time.

When a server gets deleted, I can imagine that a site goes down, and when there's a lot of sites to restore that can take time. While annoyed I could not finish the site I was working on, I think I'm quite forgiving when it comes to people doing stuff I know little about and when that goes wrong. I assume there are a lot of people all over the globe working on it who are just as frustrated (if not more), so let them do their thing. Spent the night hanging out with friends so tried not too worry about it too much.

At Tuesday morning 2am CET I received an update from Skytoaster on the situation, mainly letting me know that AltusHost was working on getting servers back online and to explain the situation. At that point it wasn't clear yet if my server was one of the removed ones or not.

And yes, it was.

A few hours later Patrick came back with a confirmation that it indeed was. We had been provided a new (empty) server which we could use to put up some sort of notice or restore from a backup of our own. The backup server, which was apparently with Altus as well, had not yet been located and the fate of that was unknown. That morning I worked with Patrick to put up a brief explanation on my websites, and started to upload backup data to try and get the site back up. Right now all articles are back up, no comments though.

I guess I'm a bit naive when it comes to servers, as I only tend to take backups when making major changes such as my relaunch back in December. That's the last one I could find on my computer, even though I recall clicking cPanel's "backup" button a week or two ago, I never downloaded it from the server after it was done generating. After all, I've been promised 7 days of backups on server-level, so in the event something goes seriously wrong with the server, that would be more easily restored than something I download manually per user on the VPS. Not a big deal, until it is.

Here's where it gets nasty.

Now, the real problems only became evident late Tuesday evening. The backup had been uploading and was almost ready when I managed to get hold off a technical support member who told me "we have no backups for our main hardware node".

I'm not sure about you, but I don't run a hosting company nor do I have the wish or expertise to start one. And I do realize in the end it's the responsibility of the user to backup what they create. But what I don't understand is how on earth someone can have the gut to run a hosting company without any backups of servers you're selling. When something goes wrong, and I do think eventually something goes wrong with any server as there's just so much things to worry about, you will want to be able of either re-routing requests to a different mirrored server or be able of restoring from the backup made last night... right? As a hosting company you would want the certainty that in case something goes wrong, you can keep your clients satisfied with a quick solution right? Well, apparently AltusHost doesn't.

Restoration Phase

After hearing this news that there's no chance of the server being restored from their end, roughly 30 hours after witnessing the first symptoms, it kinda gave me no reason but looking at getting my site back up one way or another. And this is where Patrick reminded me why I hosted with SkyToaster again as he had been working through my local backups and after getting at least my personal sites back to the way they were on December 22nd, he has been helping me manually restoring my blog articles and other websites from Google Cache in a time period of over 4 hours. Thanks Patrick!

Never, ever, ever again.

Somewhere in between, he also set up a new US based backup server (unaffiliated with the current provider) which automatically writes a nightly, weekly and monthly backup of all users on my VPS which I can access directly as well. While they made a mistake in working with Altus for their Dutch VPS, he's been working day and night (literally) to prevent this from ever being possible again.

Now what?

I'm still a great fan of Skytoasters' service. Patrick (and Sal too for that matter) are easy enough to get hold off and respond promptly when needed. They're all human, who made a mistake when signing up with Altus, but up to now all my hosting (shared and VPS) has been great. We've got most of the stuff back thanks to the hard work by Patrick, which once again proves to me they are passionate about what they do, and willing to step up when things go wrong. I'll be working with Sal & Patrick over the next weeks to find out where to move from here (they and Altus aren't off the hook yet!), but getting back up and running is priority number one.

Oh, and I'm setting up automatic downloading of backups to various locations for my own sites as well now.

Question from Twitter: "What does Skytoaster have to do with AltusHost?"

Nothing, except that the VPS I bought from them was physically hosted with AltusHost (and I've been aware of it not being one of their own servers from the get go). While Skytoaster didn't get everything right in this case, I consider most of the blame to be with Altus who knowingly risks their clients' data and, in retrospect, seems to be a bit of a shady business in general.

Read 4 comments and share your own thoughts!