Evaluating ModX Revolution

Evaluating ModX Revolution

I’ve spent perhaps 20 hours looking into ModX Revolution, a “simple” content management system (CMS) that had been a runner-up in a recent Best Open Source CMS Award back in November 2009. The winner was WordPress, which I’m already familiar with. I flipped a coin and decided I’d look into using ModX as the base for implementing “easy to update” support for the $75.00 templates. How bad could it be? I was experienced making templates for both WordPress and ExpressionEngine (sort of), so picking up a new CMS should be relatively easy, right?

Well, not really. It’s super easy to deploy a new CMS, but mastering it is a function of how well the documentation and code examples clarify the architectural and workflow decisions of the CMS designers. ModX is above-average in the availability of documentation and an active user forum, but finding a clear, concise explanation of how it all fits together (beyond toy-like examples) is taking a long time. Plus it turned out I had downloaded the old version (called Evolution) of ModX, not the swanky new beta (called Revolution), so today I had to re-install and start from scratch. It is not documented that well yet, but I’m starting to get a handle on how the designers think about the CMS and I’m writing some notes here to help me retain those insights.

Why use a CMS and not something else?

The reason I want to use a Content Management System (CMS) is because I don’t expect the average client to want to edit HTML, and I don’t want to be the bottleneck when it comes to the client’s need to update something on their page. In the past, I’ve used Dreamweaver to set up templates and required the client to use either Dreamweaver or Contribute (the “client version” of Dreamweaver) to make updates to the plain HTML files that comprise their site. However, this is an expensive solution (minimum outlay: about a hundred bucks) and Dreamweaver/Contribute doesn’t deliver a great user experience. Web-based forms, on the other hand, have come a long way in the past five years, with Rich Text Editing capabilities rivaling those of simple word processors. WordPress is a good example of a nice CMS experience, though it is geared more toward blogging, and perhaps provides TOO much power.

A simple CMS would be easier for clients, and require no outlay of cash on their part. I just need to figure out how ModX work, because it’s kind of wacky compared to what I’ve used before.

My Mental Model of the Generic CMS

With a CMS-based website, you create a “template” that is mostly HTML and with some placeholder content. The placeholders are data (text, usually) that’s stored in a database, and when a web page is requested a new HTML page is created on-the-fly by the web server. The placeholders in the template are replaced with content in the database, and the resulting HTML document is sent to the requesting browser. The advantage of this approach is that the template is separated from the content, so you can change the content without having to rebuild the template every time. You can think of a template as a kind of like a picture frame; the placeholder photo of some other person’s kid gets replaced by you with a photo of whatever you want. What I want to do is sell that picture frame so it’s as easy as possible for you to change the photo yourself. If you instead had to return the frame to me, and have me open up the back and re-insert your picture, that would be a hassle for all involved.

CMSs are founded on the basic idea that a piece of text (which I’ll call “content”, as in the “content of a box” ) can be displayed through an intermediary called a template. A template is like a display frame that “holds” content so it can be properly displayed to the world. If you get tired of the way the template looks, you can make a new one and put your old content in it. In essence, a CMS provides the following capabilities:

  • You can store multiple pieces of content in a database (usually text), each piece which has a unique identifier (e.g. a number).
  • You can have multiple templates, each of which can display and style the same piece of content in a different ways.
  • The combination of the template and content together create a complete web page. This is often called a dynamic page.
  • Content can be inserted into a template at any place, if you know its unique identifier.
  • You can change a piece of content to change a webpage, without having to change the template. This makes it easy to change what you can read on the website, without having to deal with the hairy HTML code that makes everything look right. The CMS takes care of this for you.

Nearly every CMS has some kind of programming language embedded in it, allowing the following special uses that are based on universal  computer programming concepts:

  • Content can be transformed before being inserted into the template through the use of programming.
  • Pieces of content can be  sorted by a number of criteria, such as the date it was created (useful for a blog).
  • Pieces of content can be processed one at a time in a template, each inspected before being inserted into the template.
  • Information that can be calculated can be transformed into HTML on the fly as well to create more dynamic websites.
  • Templates can contain other templates. There is usually some explicit way of referring to one template from with another, and often there are times when the CMS will include the template without you having to explicitly declare anything.
  • Content can contain other content. As with templates, content can refer to other pieces of content to be “included”.
  • Content can come from places other than the database. It can be encoded onto the URL, requested through a webservice, calculated by a program in real-time, or stored as files on the web server host.
  • Content can be turned into Template Code, which generates more content or even changes the way a template looks.

Theoretically, to create a CMS-based simple website I would merely need to do the following:

  1. Make a web page design in plain old HTML, with area designated to hold various kinds of content.
  2. Convert the HTML into the CMS’s templating language. Usually this is as simple as just inserting a “placeholder tag” where you want your content to appear; this will be replaced by a piece of content later.
  3. Create a URL for your webpage, and associate it with both a template and a piece of content.

How ModX Revolution Maps to the Generic CMS Model

Armed with these assumptions, the first order of business is to figure out where the templates are stored, find some documentation for the templating language, and then figure out how to enter your content into the system. A very basic CMS would just implement the basic ideas presented above, but in practice developers often want the ability to do more with fancy programming. ModX supports the basics and the advanced programming as well; the problem with the documentation is that is presents all the special pieces all at once without specifying the hierarchy of relationships. What I am looking for is how the basics work, and then understand how the special bits modify that. Additionally, the special pieces have names that do not indicate what they do; the difference between a “snippet” and a “chunk” is quite meaningful, but the terminology is ambiguous by itself. This is a good example of bad naming in in software design. The result is confusion.

So here’s how I understand ModX to work:

  • The content on each page is stored in a data structure called a resource. In order documentation, it is also called a document as. It’s displayed in a tree structure called a “resource list” on the left-side of the manager interface. Each resource is essentially a web page. There are standard fields: title, long_title, description, and content. Additionally, each resource has an associated template with it. You also set the page’s URL in the resource. Everything to define a simple page except the HTML markup is stored in a resource, and each resource has an id. To actually display a web page, you need to pair the resource with a Template, which select from a dropdown menu.
  • Templates are a subtype of element in the ModX nomencalture, and you have to create them from the element list. Templates can not only contain HTML: they can also contain other elements like Template Variables, Chunks, Snippets, and Plugins. Each element type has a corresponding special tag that can be embedded in the Template. For example, to embed a chunk named “foochunk”, you’d insert [[$foochunk]] in the Template’s HTML, whic  will be replaced when the web page is viewed in a browser.

Now, the more advanced stuff:

  • Each resource aka document has only one “content” field where a user can type in text. So what if you want more than just one area? You create a Template Variable, and then make it available it to specific Templates. Once you do that, when you go to edit a resource (i.e. a page), you edit the main content on the “create/edit” tab, then select the “template variables” tab to edit the rest of them. In essence, a Template Variable allows you to add additional field types to ModX. And if you think it works backwards from the way you think it should work, I am with you. Anyway, when you create a Template Variable you can specify how the data is formatted and spit out as HTML, which is pretty convenient in theory. I have yet to try it. I think you can also enter Chunk and Snippet tags apparently, though I have not tried it.
  • For those times when you want to include static text or HTML in your template, you can create a Chunk. Chunks are actually parsed for tags, and their output is cached. Chunks can’t contain PHP, but they can contain references to Snippets and ModX Settings (e.g. things like the name of the website). Snippets are invoked from within a Chunk using a Placeholder syntax that can pass along some simple formatting codes. Snippets NEVER generate HTML, so the Chunk’s responsibility is to “wrap” snippet output.
  • And when you want to include data-generating PHP code in the template, you can create a Snippet. From within a Template, Snippets are invoked using a kind of function-call syntax, with variables set within it in a way similar to (but not exactly like) the &var=`val` syntax seen on httpd GET-style forms pages. There is some kind of magic used to connect a Snippet to a Placeholder that I haven’t found clearly stated; it may be that all installed Snippets check for placeholders in the current Chunk.

So I think that’s how it works. The general philosophy behind the workflow is to create all your elements from the bottom up, then build your resource from those elements by linking to them.


  1. Nils Geylen 13 years ago

    This is a valuable post Dave. It never ceases to amaze me how you often go on on not being productive enough and yet you manage to output all this great content. That said, while this doesn’t seem to be following the usual way of thinking, it does look interesting enough to install and play with. You’ve sure done your part. In addition though, have you tried Perch? It’s said to be a “tiny” CMS and I’ve heard some good stuff about it. Not free but you can get limitless trial versions (requiring renewed install each time of course). Cheers and keep doing the amazing work here.

  2. Author
    Dave Seah 13 years ago

    Hey Nils!

    Thanks, man! I appreciate the encouraging feedback!

    This post is a good example of the different perspectives we’re coming from as poster and reader. It took 20 hours of thrashing for me to gain the insight to even write this post, and the post itself was not the actual thing I wanted to do; I had to write it to get the final bit of clarity I needed so I could actually use ModX. The breakthrough moment was when I realized I should write down how I expected a CMS to work, and map ModX onto it, rather than glean the theory of operation from the documentation. I need to remember that. Anyway…20 hours to 1 post seems like a terribly inefficient use of time to me compared to 20 hours of solid engineering work. Hence, the frustration and feeling of lack of productivity.

    However, from the reader perspective, you just got 20 hours of pain distilled into one quick read, thus avoiding you 20 hours of pain. That must feel pretty productive!

    I suppose what might make me feel better is knowing whether it takes people as long to get something working. I historically have felt I do not learn well from documentation, and had assumed it was some fault of mine not having the requisite background. It’s only recently that I started to realize that the documentation was potentially just really bad to begin with, yet I am the only one who complains. Since that seems to be the case, my assumption is that everyone else can use it just fine.

  3. Nils Geylen 13 years ago

    Interesting POV but one that seems valid enough. One such example I’ve encountered is with Inkscape, the open source vector tool.

    I’ve often tried to read their ‘manual’ only to fall back again to just trying to make it work myself. I know that I’m probably missing out on some of the essential basics but so far it has done for me what I need it to do.

    Now when something doesn’t work out the way I’d like it to I chalk it up to myself not knowing enough instead of not having grasped the manual – which too often is in fact too superficial to begin with. You are then, in fact, not the only one who seems to think they’re the only ones complaining or having a difficult time.

    What I learn from this is that perhaps writing down your own experiences might well work both for yourself as for the community. In the end this post will serve someone else who complained but never made the effort to publish on it. Thank you for putting the time and effort into it.

  4. Jay Gilmore 13 years ago

    Hi David,

    Jay Gilmore here from the MODx team. Great post. Great points. You are well on your way and certainly on the right track. I started w/ MODx in 2006 and it took me a lot longer than 2o hours to get this far.

    As a note on versions, the PACKT Publishing CMS Award was judged on MODx Evolution and not Revolution as Revolution was still in Alpha during the nominations and few people had been using it.

    Let me say you are not alone in your struggle to learn from the MODx documentation. Many people learn from a number ways, some are get in and muck about, some are read the words, api and etc. and others like videos and picture and there are people like me who like a scattered combination of all.

    The documentation of a product in development is a challenge, MODx Revolution is pretty well complete in terms of features but we are still adding and improving as we move to RC1 (as I write this it is getting pretty close). That being said we know and always strive to do better in helping people new to MODx to learn how it works. We have begun recruiting and encouraging community members to aid in the documentation. Any suggestions on how we could improve the documentation is surely welcome. We are an open community with a receptive team.

    My own personal experience with MODx (pre Evolution as I started out with MODx 0.9.2x) was a challenge. I struggled to really understand it but found one of the best ways to learn MODx was to ask questions and try to solve other newbie problems.

    I would love it if you keep posting your experiences and sharing what you learn and don’t hesitate to help make our documentation better.


    Jay Gilmore MODx Marketing, Community and Social Networks

  5. Author
    Dave Seah 13 years ago

    Nils: I think you’ve identified the key point for me: sharing is good! I’ve solved many a problem by a quick Google, where someone has posted some esoteric hint that really made the difference. Thank goodness they posted it in the first place! The second thing is that when I write something down, I often clarify it for myself. I perhaps come off as too harsh in my condemnation of bad documentation, displacing my frustration into a belief that my own documentation is better. It probably isn’t. It’s just different.

  6. Author
    Dave Seah 13 years ago

    Jay: Thanks for clarifying the version information, and indeed the open community was one of the great draws of ModX; that’s always a good sign. I hesitate to ask questions that are so basic that I could probably answer by sifting through the source code myself, but I probably should get over that and just post away. Thanks for dropping by!