Stand With Ukraine. Stop Putin. Stop War.

This article has been translated to Russian as well. Know of any other translations? Let me know!

MODX has very granular caching possibilities. Where Evo limits caching to just snippets and has other limits in terms of embedding tags in tags, MODX Revolution does not have these limits.

In MODX Revolution you can cache / uncache any tag you may use. That includes snippets, but also setting tags, placeholders, chunks and even lexicon strings. This article will talk you through some reasons when to call what cached in MODX Revolution (but it will save you most of the inner workings).

It is important to realize that, unless you're doing real advanced stuff and have overriden the core caching, the cache will be cleared when you: save a resource, element and to some extent settings. So basically, whenever your content or structure is changed - your cache will be updated to reflect that.

How do I tell MODX to (not) cache a certain tag?

Simply add in the exclamation mark (!) in front of the token. The token is a dollar sign ($) for Chunks, a plus sign (+) for placeholders, a percentage sign (%) for lexicons and an asterix (*) for resource fields and template variables. Snippets do not have a token.

Examples cached:


Example uncached:


Four Guidelines for Caching Strategies

  1. Cache everything you can.
    In general you will want to cache as much as you can - why should MODX retrieve the content from the database on every request, when it hasn't changed? While this may seem logical (and there is rarely any question on wether to use resource fields cached or not), the same applies to other tags. If the output of a snippet doesn't change on every request - why should MODX parse the snippet on every request? It shouldn't.
  2. User-specific output needs to be uncached.
    Anything that outputs user specific information will need to be uncached. Simple - any request could be made by different users, so it wouldn't do any good to load user-specific information from cache. This applies to snippets that interact with the user system (the Login package, a Wishlist component but also Quip for commenting), but also the somewhat less known [[!]] placeholder.
  3. Content related to URL parameters or POST data needs be uncached.
    If you're using a form which displays information about what was posted, you don't want that to be fixed and cached. So call that uncached as well. If your output is different depending on (non-id/q) URL parameters (for example a search results page), you will want to make sure the related snippet is not cached.
  4. Use custom caching when needed.
    If data (in a snippet) changes before the cache has been cleared, for example if data is retrieved from an external XML source that changes independantly to your MODX Content, you will want to use a custom caching method such as the getCache snippet or write your own caching within the snippet code.


Of course there are exceptions...actually, I could only come up with one so far: (Updated October 26th, came up with another one!)

  • site_url, http_host and related system settings may be called uncached. If you have a certain setup in which one resource+template combination may server multiple urls, you will want to make sure the related system settings are called uncached. One common application for this is your <base href="[[!++site_url]]"> tag for friendly URLs: you will want to be sure your assets are served from the same domain as the user visited. Wether you should force www/no www through htaccess is a whole different discussion, but that is very much related to this and a common cause for issues.
  • Snippets that (may) redirect or forward elsewhere will usually need to be uncached as the result may be empty, but the processing of the snippet does the work to redirect the user.

Common Errors

  1. Calling the "if" snippet uncached, when the subject is a resource field. Most likely caused by the documentation having uncached examples, a lot of people mis-use the If snippet by not caching it when the subject is static for the cache lifetime.
  2. Calling the "Wayfinder" snippet uncached. Please don't! Wayfinder especially can take a good performance hit on your website with larger menus. The only valid reason I can come up with to call Wayfinder uncached is when the output is user specific (member-only area, for example).
  3. Uncaching placeholders in chunks that are used as templates in snippets. Uncached placeholders are processed at the last possible time, and calling them uncached in a template will leave them in tact and they wont get replaced by the snippet, but instead by the core parser long after the snippet is done. (This behavior has seen some changes/bugs in the 2.1.x releases, so it could be that this is different in the latest release - I haven't actually checked in much detail recently.)

What are the errors you have made that you spotted in the above lists? Or do you have other caching tactics or questions? Share below!

Based on a comment from Marc Hinse, a follow-up to this post has been written discussing how nested caching works in MODX Revolution.

In some languages (the Dutch one for sure) on smaller monitors/ browsers (1024px), the top menu in the MODX Manager overflows, pushing the last two or three items down a row, rendering it useless.

I've created a simple plugin to fix that called TopMenuFix, and has been added to the Extras repository

And with simple, I mean really simple. As the menu is simply styled with CSS, all it has to do is override those styles on manager pages. We'll be using the onManagerPageInit event to put some style definitions on the page automatically.

This two line plugin calls the modX::regClientStartupHTMLBlock method, which sounds really complicated but just injects some html into the header of the page. In this case, that is simply this:

And that's all there is to it.

Want this too? No problem! I've wrapped it up in a package using the PackMan addon and it is available from the Package Manager It's called "TopMenuFix". You can also find it on the MODX Website.

The source is on Github and with any bugs or feature requests (I don't expect them.. but.. okay) please also post on the TopMenuFix Repository Issues section.

The manager on my site handles a couple of site. First of all it is, obviously, where I write these articles. Then there was a Dutch translation in the works in a seperate context, as well as another one for the HandyMan website. Every now and then there's somebody who helps me out with these. There's someone translating for me, there's some people who help out on the HandyMan website and then a few more that need access to my main site.

At first I just gave them all full out access, but to provide a little more customization and security for myself I decided to set up a couple of user groups with just the permissions people will need. One of these involved the elements such as chunks and templates. Users working on the HandyMan site don't need access to my main site template or the other way around.

So I set up some access levels. I decided to do it quickly, and set up one "MH Admin" group which has access to the main site context and its elements. That would mean any other user groups (minus the main Administrator one which already had access to everything) only has access to the others. This is, in case you don't know yet, because the security system locks out user groups that do not have the permission in case you set it explicitely. So first everyone's allowed - but when you give one user group explicitely access to it, it will block all the rest. No problem! That's exactly what we want.

Fast forward a month.

It is now June, and a week ago I updated MODX to 2.1.1-pl, and set up a new context related to the development of a new website - this one! Fresh content, fresh layout etc. All good. But suddenly, a week after setting that up, while browsing the site it seems some pages have eaten their template! Nothing shows up, but just the content.

Theory 1: corrupted cache

Okay... odd. Now let's think. What could've caused this? Let's just refresh the cache to make sure we're not just dealing with an incidental corrupt cache or anything. Cache cleared, back to the website, all good. Alright then - back to work!

Theory 2: context settings

Now about an hour later I end up watching my website again, and guess what? Same problem all over again! I didn't settle with clearing the cache this time, but instead kept browsing around in order to see if I can replicate it on the website. At one point I just totally couldn't find it and decided to make a note about it on my homepage just in case it would happen again. So I make the modifications and press the "View" button to check how it looks. But wait! The "View" button doesn't work, but attempts to open a javascript code as webpage. So I went to check the site_url setting in the context, to find it wasn't there.

I never set them on the "web" context for the simple reason that it wasn't needed. The web context runs just like it would be the only one. But, or so I guessed, the fact that I recently added a development context for my new site without settings either (did not want it public yet) might have been the problem. Let's set some settings such as site_url and try again. Yay, it's back up!

... or is it?

What actually was the problem

The problem was that it would not be parsing my templates, chunks and so on. My elements. The same ones that I protected a month earlier in the back-end to make sure only the people I want to be able of accessing could actually see them. After receiving another text message asking if I made my website "Mobile friendly" (yes, that's you Taco!!) it seemed the problem was still there. Aaargh!

Figured it out yet? If you didn't, don't worry - at this stage I didn't either. If you did, where were you when I needed you?! :P

If you remember (or scroll back up) you'll see how I explicitely set my MH Admin user group to be able of accessing these specific categories. What that meant is that any other user groups would not. But that's what we want right? Actually - there's one flaw in there, which may stem from still being used to the Evolution security systems in which you had the division between web and manager users. In Revolution, you do not but instead they can be used for both or just one of them. The user group that caused this was the (anonymous) one - a user group representing people that are not logged in. Site visitors. People who will want to see my templates and other elements.

So because I only explicitely allowed my MH Admin user group to access these elements, they were automatically hidden from other user groups.

Including valuable visitors.

The fix was easy - just give the (anonymous) user group access to these elements as well, using the access control of "Load, list and view". Flush permissions, clear cache and back to the site. Test in three browsers and ask three other people from all over the country to do the same. I am now confident to say the problem has been fixed.

So that's all?

Now there's one more thing that I didn't explain yet, which has seriously made this fault hard to track down. I know this system quite well, and this had me puzzled for days.

One word: Caching.

My site is cached as much as possible, which includes complete resource caching. So whenever a page is requested (by anyone) it is cached. This anyone is often me - whenever I change something I check it out, and click around a bit to check out comments etc. All the resources I visited were added to the cache, and these often were the ones that were most visited as well. So whenever I visit a resource while being logged in, it gets cached with my permissions.

But, and this was the problem, when a resource was not cached it would use the anonymous user group permission and MODX would refuse to display the templates and other elements. As a result it would just dump the content with no errors (it's intended behavior, not something failing) or any clues.


So that's what kept me busy over the past period. And I hope this article can prevent you from having to do the same. :)

It's possible that you don't know what the MODX Partner Program is, though it has been getting more and more attention lately. There's not a simple explanation to that as it becomes as much as you put into it, and much of it is constantly in development to offer more benefits to the Partners as well as MODX.

In general it can (and has been) said that it is aimed at developing MODX and your own business by offering resources, a private discussion board and closer contact with the core developers. Depending on the size of your company, there are three levels you can choose from: Professional, Agency and Premier. Where Professional is the cheapest (at $ 500 per year at launch, but as of June $ 50 per month) level, it does come with the advantages mentioned above and also includes a complimentary license for PhpStorm and New Relic, a Partner Listing valued at $ 100 per month and of course access to the partner board. Moving up the levels, the price increases (to $ 5 000 and $ 10 000 for Agency and Premier partners respectively) as well as the benefits such as 5/10 hours of core consults, a MODX integrated helpdesk suite, sales leads and much, much more.

In April I decided to take the plunge, and sign up to become a Professional Partner and see if it is worth it. As you may know, I am a freelance developer and even though the business is running well, at that point $ 500 was still a lot of cash and making the decision to try it out didn't come easy.

Taking the plunge

The first few hours of being an official Professional MODX Partner were mainly spent visiting the private forums, which are packed with other skilled MODXers discussing topics varying from favorite development IDE, development and quality assurance workflows, what they were working on and so on and so on. While the public forums are amazing as it is, there is something about the Partner boards that the public ones just don't have. For example when looking at help requests, it is easier to share bespoke code as the forums are not indexed or otherwise publicized, there is a less demanding atmosphere and they don't just deal with how to use basic MODX properties, but go more into depth challanging the system and the people using it.

Furthermore - there's the scoop. Lots of it. Think about a first look & test run at the new forums, a topic explaining what has changed in 2.1 before the public launch and more. It may be hard to put the value of such forums into money, but for me personally there is a great wealth of information there and lots of dense-packed knowledge from the core team as well as other partners.

A second point that has really attracted me to take the plunge was the MODX Certification. At time of writing this has not yet been fully developed, but it is expected in the third quarter of this year and will provide a huge advantage to show credibility and knowledge. Especially for the smaller companies or freelancers like myself, credibility is often one of the bigger challanges in doing business, and this will be a huge help to get that obstacle out of the way.

Three months later - was it worth it?

Short story: yes.

In the past months I have not only learned a lot about MODX, but also about different tools for development and email marketing, read about the differences between MODX and another system in detail and my business is running like crazy. Joining and actively participating in the program has introduced me to new people and has led to new inquiries - a big bunch of them from other Partners looking for people with my speciality. In June I was also contacted for a promotional activity, which you can see the result from on the Partner Program page.

Everyone will have a different idea of the partner program, and different benefits attract different people. There's designers, developers and decision makers involved but they have one thing in common: they support MODX and have been willing to contribute towards further development of it as a system as well as a company. 

You ended up on this page. Either via Twitter, Google or another source - but no matter how you got here, you probably want to learn a little something about the MODX system. This article will attempt to explain what MODX entails, what it can be used for and also some basic information on how to do so. If you are already experienced with the system - this article is probably not for you, but don't fear - I have plenty of other MODX Resources you may be interested in!

This article assumes basic knowledge of web development languages such as HTML, CSS and to some extent PHP. It does not assume a certain MODX skill level.

First things first

Now, before I start telling you what is so awesome about MODX, let's start by a short introduction of what it is.

First of all, you should probably know that there are two branches, or two different products. They are called MODX Evolution (version 1.x) and MODX Revolution (version 2.x). While both are developed by the same company, actively maintained and share the same core principals they are quite different still.

MODX Evolution is the legacy code - the code that was first developed back in 2005 based on a different content management system that did not meet the developers' requirements. Since July 31st 2009 (the release date for 1.0.0, which was preceded by over a dozen alpha releases that I cannot find data for anymore,  unfortunately) this product has been downloaded roughly 475,000 times and has found its way to a lot of websites.

With the release of MODX Revolution, the Evolution branch has not been deprecated but will be supported for a long time coming. MODX Evolution installs on pretty much all shared servers easily, and is powered by PHP and MySQL.

MODX Revolution, the current flagship product of MODX LLC, is a complete rewrite started somewhere in 2007, based on xPDO (more about that in a later article), and gives a lot more power and freedom to designers, developers and end-users. The first stable release (2.0.0-pl) was released on July 22nd 2010 and has been downloaded over 160,000 times so far - and counting. In June 2011 MODX Revolution 2.1 was released which included a couple hundred fixes compared to 2.0.8 and also marked the removal of deprecated Evolution code that was included in 2.0 to make transitioning easier.

This article was written with MODX Revolution 2.1 in mind, however most of it is also applicable to MODX Revolution 2.0, or MODX Evolution 1.0.5. Revolution 2.2 also shares the same principles, but adds a number of new, fancy features.

What is MODX?

In its purest form, MODX is a php application that allows you to easily manage any content on your website or intranet. However, that's just getting started and does not yet explain why it would be a good match for your next project.

There is no singular definition of MODX, for the simple reason that its flexibility and ease of customization allows you to easily customize the experience for the end-user, without limiting you in any way or requiring hacking into the core files. I guess most web developers and designers will know that there is always the right tool for the right job, but the way MODX has been developed allows you to use this system over and over again, without having to fit your project into certain paradigms, boxes or widgets. On top of that, there is not a single way you can do things within MODX. There's always at least three possibilities and you can choose the right one for you based on your knowledge and time available.

Managing page content

MODX is based around a sitemap-like Resource tree. Resources are, simply put, your website pages, but they could also be used as products, blog posts or even RSS feeds. There are actually four types of resources you can use, which all serve their own purpose:

  • Documents are the main resource type that simply holds your content.
  • Weblinks are resources that instead of actually containing content, creates a redirect or link to either another resource or an off-site link. This allows you to manage links in dynamic menus or create shortcuts into your website.
  • Symlinks are similar to weblinks, but instead of redirecting they create a copy of another resource which remains synchronized. You can change a couple fields in a symlink, to give it a different title or description for examples.
  • Static Resources are files on the fileserver that you "link" to that can be used just like other resources. For example for listing PDFs in  your dynamic menus.

Roughly 98% of the resource you wil use (depending on the type of jobs you do, obviously) will be Documents, however you will often see the terms "Resource" and "Document" mixed up as it's all some people use.

Trivia: prior to Revolution and Evolution 1.0.0, what is now known as "resources" were actually called "documents". These terms were then streamlined to what it is now.

MODX does not use a templating system

It may sounds weird - but really, there is no templating system in MODX. You are not forced to write in a certain language (though HTML is advised, but that is cause most browsers support that out of the box). You are not forced to put your precious design into a certain block, sidebar, header or footer container. MODX just outputs what you tell it to. There are plenty of screenshots of sites build in MODX in the MODX Sites Showcase and added to the MODX Club that will show you that there are no pre-defined website or markup structures. Your imagination (as well as time and skill, obviously) is the limit.

So how does MODX get this almost impossible infinite freedom?

Basically because it was built to take in basic HTML (or XML, or CSS, or JS(ON), or even that new language you have been developing!), in which dynamic content is inserted using what are called "Tags". Now don't get scared - it is not an entirely different language you will have to learn. Here are a few examples of Tags in MODX Revolution (2.x):

Tags always start and end with two square brackets, and after that there is a token. A token is what defines the type of content to replace the tag with. This can be a resource field (*), system setting (++), link (~) or others. Another type of tag, which does not use a token but just the square brackets, is a snippet. We'll get to those later.

Remember that these are the real basics. Don't let this simplicity fool you though - we are not even touching the tip of the iceberg yet, however as I want to save more advanced (though still easy to use) features for a later article. There is information about the tag syntax in MODX Revolution and Evolution in the Documentation showing the basic possibilities as well as more in depth technical explanations.

Now, to bring this way of templating into context, here is what your HTML5 header part of a template could look like in MODX:

You will see that I have, besides the pagetitle field and site_name setting, also referenced the site_url system setting, but this time I added an exclamation mark (!) in front of what is called the token - this indicates that we want that to be fresh on every page load, and make sure it is not cached. We are using this on the site_url system setting to make sure we are getting the right one at all times - the website may have been accessed at or, and we don't want stuff breaking (think cross-domain ajax requests) because of that. You can read more about Caching Guidelines in this blog.

What you may also notice is that we added a property to the tag in the canonical link. A property is an option or parameter you pass to a certain tag, which can then be used by whatever it is that is processing the tag. You can apply this to Chunks as well. In this case, we told the link tag processor to use the "full" scheme, which means it will generate a link pointing to the current resource complete with the site url prepended. You can find the technical explanation of the PHP method powering the link tag in the documentation.

For the page you are currently viewing, the above code example would get parsed to the following:

Now this is just an example of course, and there is a lot more that you can do with these tags that will no doubt be explained in upcoming articles. We haven't had all different tags yet though - there are a few more that are directly linked to what are called Elements.

Blocks, Widgets and templating evolved: Elements

Again - elements are just what you make from it.

There are a few types you can use:

  • Templates, which just hold the markup you want a resource to output. They are linked to resources directly but can be reused into infinity. We explained the real basics of templating above, but remember that virtually anything is possible.
  • Template Variables, which are resource fields on steroids. I've been told this is like the CCK module for Drupal and Joomla!, but then included in the core. Within MODX, you can access these in the same way as resource fields, using the asterix (*) token in a double square bracket tag: [[*tvname]]. Template Variables are very powerful and can probably use a couple of arcticles on its own. There are input types (such as image, file, number, grid data (using MIGX addon), dropdown boxes, checkboxes etc) and output types (raw, html tag, delimited list etc) that can help you set up hassle-free content editing for clients.
  • Chunks, reusable chunks of.. anything (except php). Can be accessed with a double square tag, using the dollar sign ($) as token: [[$chunkname]]. These are often used to split up a template into reusable parts, for example that block of code earlier representing a header could be used in a snippet, which is then called in different templates for easy updating.
  • Snippets, which are php addons to do whatever the addon developer intended it to do. You can use snippets to create lists of resources (menus, but also including summaries), search the website, or really anything that can be developed in PHP. You can use snippets by just specifying the double square bracket tag, without token: .
  • Plugins are developed in PHP and hook into system events, which are triggered throughout the manager as well as on front-end requests. They are used to extend core functionality without breaking upgrade paths. There are plugins available for rich text editing (TinyMCE and CodeMirror for markup), automatically resizing images referenced in a page based on its attrobutes (AutoFixImageSize) and also for internationalization (Babel).

These elements can be catagorized in categories and are all managed from the back-end manager and can (and should!) be easily cached for fast loading.


Now that you have an idea of what different terms refer to in MODx, you're probably good to go and start playing with the software. This is (if even that) only touching the tip of the iceberg though, just to get you understanding the main concepts. I would like to suggest to start by downloading MODx, and installing it on your test server to start working in MODx. Would you rather dive into MODX with some guidance? Check out Mary's MODX tutorial series over at the Coding Pad where she takes everything step by step, creating a full website from a CSS template.

And always remember: there are always multiple ways to do one thing in MODx.