Stand With Ukraine. Stop Putin. Stop War.

One of the powers of MODX is its flexible templating. The biggest part of the flexibility boils down to the different types of tags that can be used in Templates which replaced with the dynamic content specified.

While the different tags are listed in the Documentation, not all of them are properly explained and some take time to really make sense when you just started using MODX. This blog post will explain the difference between two tags that are very often confused with eachother: placeholder and resource field tags.

Let's see what the two terms actually mean and which is which.

Resource Fields

A resource field is a field of a resource. Oh, you figured that out already? Great! So if you fill in fields of a certain resource in the Manager, the value of that field is available through the resource field tag. What is important to realize here is that you can use these tags, no matter where they are used (in templates, chunks or elsewhere), will take the value for the current resource. So if you're viewing the homepage, a resource field tag will get the value from the homepage resource. If you're looking at a contact page, the resource field tag will be replaced with the values of the contact page.

It may seem logical or common sense (and really, it is!), but that's where placeholders differ from resource fields. 

Resource fields use the *asterix* token in the tag. Some valid examples:

And their values for the current resource:

Title: February 2012
Menu Index: 1
Content (not shown to prevent the page from breaking!)


A place holder can be anything. 

Yes, really. Anything.

The key thing to realize with placeholders is that they are being specifically set by usually a snippet or plugin. That snippet or plugin decides what a specific placeholder will get as a value. Some snippets such as getResources or my getRelated iterate over resources, and they assign placeholders with the same name as the resource field. 

Let's go a bit more practical.. You may have a resource listing on your homepage (for example the latest Articles), retrieved with the getResources snippet. Your Homepage template will probably use the Resource Field syntax to display the current page's title in the <head> part:

Your getResources snippet on the other hand uses placeholders to provide you with information on the resource it is looking at. With getResources you specify the &tpl property which is the name of a chunk that will be used when iterating over resources. The chunk may look like this:

This means that when getResources reads the resources with ID 2, 3, 4 and 5, it will load the tpl chunk four times, and assigns values as placeholders each of those four times. The first time it loads the chunk it sets the values to the resource fields of resource 2. The second time it takes the resource field values for resource 3, the third time for resource 4 and finally for resource 5. So in this case we have placeholders that give information on a resource which is not the current resource.

Resource Fields always contain values for the current resource, while placeholder values can be anything from other resources, custom tables or simply random stuff. 

A note about Placeholders

While placeholders are usually set by snippets or plugins, that doesn't mean that's the only way they can be set or used.

You can also add parameters to a chunk tag, which can then be used as placeholders within a chunk. This is a nifty technique if you only need minor changes depending on the template, and want to prevent repeating yourself.


New Extras are released all the time, MODX LLC is always working on the next big thing and the Community is growing exponentially. In this series I'm going to try and keep you posted on interesting initiatives and stuff coming up. Welcome to Episode 1!

In this episode:

  1. [Extras] Interesting new TV Input Types
  2. [Extras] All things Analytics
  3. [MODX] Mostly Cloudy, with a 100% chance of MODX™
  4. [Evolution] Security fix for 1.0.5 now available

1. Interesting new TV Input Types

Many consider Template Variables the number 1 reason they like MODX, which is definitely something I can relate to. However, did you know you can also develop new input types to bring it all to the next level? Well, you can!

A lot of people know about MIGX, short for Multi Items Grid TV (for MODX?), which allows you to work with a grid, or table, enabling you to add an unlimited list of items. I think it could use a cleanup, but it does what it promises on the tin and I use it quite often. 

In the last few weeks, a couple more interesting TV Input Types have been released. ColorPickerImagePlus TV Input and SuperBoxSelect.

ColorPicker is not exactly new, the first version was released back in November, but it gives you a pretty nice colorpicker with different output types (such as HEX, RGB or JSON). If you allow users to change the color of certain template aspects, ColorPicker sounds perfect for the job.

ImagePlus TV Input is for those times where the default image cropping of PhpThumb(Of) is not enough, and you need to define exactly what is shown yourself to prevent weird results (like seeing only half of a face). While there's still a few bugs and I wouldn't recommend production use yet, this is definitely something to keep an eye out for as it gets further developed.

SuperBoxSelect, by the same author as ColorPicker and also first released in November, is a variation to the default ResourceList input type which allows you to select multiple resources through a combo (dropdown/select) box. 

2. All things Analytics

We all like Google Analytics (and making sure manager users don't show in the stats!), and over the past period a number of addons specifically for Google Analytics have been released.

First we have the Google Analytics Dashboard (for 2.1), its MODX 2.2 spin off using a Dashboard Widget and Big Brother, all of which request the Analytics data through its API (after authorization of course) and shows it to you the moment you login to your Manager. I've been using both the GA Dashboard Widget and Big Brother, and I have to admit I prefer Big Brother. Its authorization process was smoother (and looks super fancy, too!), and more matched the information I expected on the dashboard.

We also have two extras to put the analytics code into your templates, which are Analytics and Google Analytics (the naming isn't as original as Big Brother!). 

3. Mostly Cloudy, with a 100% chance of MODX™

.. or at least that's what the MODX team is telling us!

MODX Cloud, which is currently in private beta, will (again) revolutionize the MODX world by offering a cloud based platform where you get a fully configured installation of MODX Revolution in the Cloud. This new infrastructure, which is powered by MODX Sponsor Softlayer, will likely come with all the flexibility and benefits of cloud hosting: super fast and easy deployments, easy migration between servers and of course scaling with a click of a button (if that!) when you most need it. Rumours tell me there are some specific MODX benefits attached to Cloud as well (no specifics here though!), and from the looks of it you will also be able of getting access to MODX Cloud through the all new "coming soon" MODX College.

Seeing how the Revo development on Github has been a tad slower lately compared to the past weeks, I'm going to bet the team is working hard to get this out there! ;)

4. Security fix for MODX Evolution 1.0.5 available

Last week a critical security issue in Evolution 1.0.5 was discovered, which allows certain (Extra) configurations to be exploited, resulting in executing of snippet tags. Some people have indicated added files in the assets/cache folder which did not belong there and may have provided an entry point for further exploitation. More details in the Security Notice on the forums

The fix be applied manually by replacing the contents of your manager/includes/ file with the version on Github. Alternatively MODX Evolution 1.0.6 should be available soon with this fix and possibly more.

In the next episode...

I've got some ideas for the next in this series, but do let me know what you would like to hear about! The next episode will probably arrive in a few weeks.

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!

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.

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.