Hello! Welcome to my humble web presence. I'm Mark Hamstra, 28 years young, wearer of many hats at modmore, resident of Leeuwarden, the Netherlands. Most of my time is spent building and maintaining awesome extras and tools at modmore, but I also love gaming, cooking, and my dogs. More about me.

This site is where I share thoughts, cool projects and other oddities related to MODX, xPDO and ExtJS. I also write about MODX regularly over at MODX.today. Sometimes I post three blogs in a week, sometimes there's nothing new here in a year. Read a random article.


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 domain.com or www.domain.com, 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.

There is something, well, maybe not magical, but certainly productive about using xPDO queries within MODX as opposed to using plain SQL. I've created a really simple snippet which fetches children of a resource (if any) and outputs them in an unordered list. And this took no more than a few minutes to pull off.

Before getting started

You may be wondering what xPDO is. If you've not wrote custom code in MODX Revolution yourself yet, I can imagine the term might not sound familiar. xPDO stands for "open eXtensions to PDO" and it has been developed by part of the MODX Core Development team to provide an Object Oriented Programming approach to relational databases built upon PDO - a core function of PHP > 5.1. At the same time, it also provides (although slightly limited) support for PHP versions under that.

Anyway - that's not what I wanted to explain in this article. This article is about how you can use xPDO within MODX to easily create custom snippets which are very easy to read, fast to execute and can be customized at will without spending years learning a special language - it's all PHP.

getChildren

I designed this snippet cause I needed a simple way to output an unordered list of children of the current resource, but where using an existing addon (like getResources or Wayfinder) would feel like overkill. Of course they both have their own advantages compared to using this custom approach, but I'm being given the power to use this by MODX, it's probably faster (I didn't test it - but just have a look at the lines of code getResources uses and what my snippet uses) and I wont be touching it often after developing it anyway.

This is the actual snippet I'm using:

It's commented line by line, and those familiar with PHP will see what it does in an instant. There's a few things I'd like to point out in this case though:

  1. The script starts off with calling the $modx->resource->getMany('Children') method. What this does is tell MODX to use the current resource, and find associated children based on that resource.
  2. On line 6 shows the modX::getOption (inherited from xPDO:getOption) method, which is considered best practice to get settings and properties from in MODX Revolution. It accepts three parameters:
    1. (string) name of the option (setting, property) you want to retrieve. In this case I'm looking for the tpl parameter.
    2. (options array) variable name you want to get it from. Within snippets you'll use $scriptProperties.
    3. (string) default value if there's no value found for the option name. In this case I set it to an empty string.
  3. When it starts going through each of the children found, it first sets an array with the different resource fields I want to have available in my template chunk, and get the value using the ->get('fieldname') method. When it has all the data in the $out array, it will take those fields and use $modx->getChunk($chunkname,$placeholders) to populate the template with the placeholders, and in turn add that output to the $o variable.
  4. Lastly, it finishes the outer markup and returns the output to the snippet call.
Now let's look at the tpl chunk.

The chunk is really straight forward. It creates a list item element, adds in an anchor (hyperlink) tag and uses the placeholders that are set. It also uses the link tag syntax to create a link and the "default" output filter, which sets the value of the placeholder to what's included in the `` quotes if the placeholder value is empty. So in this case, that acts as a backup in case I didn't set a menu or a longtitle (assuming there will always be a pagetitle).

What remains now is showing you how to call it (assuming you named your Snippet getChildren, and your chunk getChildrenTpl):

Conclusion

Don't be hesistant to coding your own snippets - xPDO and the MODX api makes the most common tasks ridiculously easy. This snippet took a couple of minutes to make and by spending a couple more minutes you could improve it easily to also use an outer template instead of mixing PHP and HTML... but it suited my needs as it is :)

What do you think about using custom coding in your development?

Heck, I could write a long post about Zen Coding - but why not just let you see a vid that explains it, and shows some of its amazing features?

Check it out at Vimeo - Zen Coding v0.5.

As my xHTML writing tool of choice is Notepad++ (due to it having syntax highlighting for like, everything) I did a few googles to find a Zen Coding plugin for Notepad++. Chances are that your favorite editor also supports it, or that a plugin is available from the Google Code project.

How it works

Simply type in a string such as this one, which reflects the hierarchy of html tags:

Then use the shortcut your editor uses to expand the Zen Code into xHTML (for the Notepad++ plugin that is Ctrl+E, later versions seem to use ctrl+alt+enter) and watch how, magically, you end up with full blown, indented markup.

But that's not it! There's more! Do you also have the same markup layout structure of a container div, containing an inner container, then a header and content div? Does your header div have a logo img? No biggy!

transforms into

You could literally build a whole page's basic structure with this in minutes... I'm in love.

Oh, and this one is even better. If you use "html:5", you get the complete HTML5 structure, including doctype and what not.

If you're looking for a total list of possibilities, I suggesting getting this 7 page cheatsheet, which also includes the Zen CSS properties.

MODX Revolution features a number of very powerful features that are hidden under the surface, but when discovered are hard to live without. Two of these are Element Properties and Output Modifiers. This short article will give you a quick introduction on what they are, and how they could be used.

What we will want to achieve

Do you have some kind of breadcrumbs trail in your page's  title, which should display the parent of the resource you are in? Great - but we don't want that on regular pages. Our regular pages and blog pages (where we want the parents title in our page title) are in two different templates, but they share the same header chunk. We'll want to use  the same header chunk, but make it output different contents.

So how do we do this?

We will tell the chunk in the blog template to output the parent (using an element property), and in the chunk we will add some conditional logic (with output modifiers).

Let's assume the following to be your template.

What we can do there is assign a property. Assigning a property can be seen as adding a variable or telling it to do something. When we put snippet calls in our template, we tell the snippet what to do using properties. For example, a Wayfinder call could have a startId and level property telling it how to process your menu.

Those properties we assign to snippets is something we can also assign to other elements (chunks and template variables are most applicable in this case). Knowing that, we can use the following to tell the core.header chunk to show the parent:

Just doing that wont do much... we will need to adjust our core.header chunk to make use of the property we pass to it (showParent), and based on that output the parent's title or not. When using properties with chunks, they will be added as placeholders so we can access that with the placeholder syntax. Let's use that, and throw in the conditional logic we need.

Let's say this is the relevant part of the core.header chunk:

After making the changes, it will look along the lines of this:

Okay. Let's break down what we did there.

  • First it simply fetches the pagetitle.
  • Then it fetches the placeholder we just set with the &showParent parameter on the chunk call, and do some magic with it:
    • It first checks if the placeholder is not empty (or: does it have a value?) using the output modifier "notempty". If it does, it outputs ":: [[*parent:getPagetitle]]". If it is empty it will return the placeholder's value (which is then nothing).
    • [[*parent:getPagetitle]] is where we use another output modifier, a custom one (snippet) this time, which fetches the parent's ID and parses it with a small snippet to get the pagetitle.
  • Then it simply sets the rest of the title.

By checking if the parameter showParent is empty, you're creating a way to conditionally control the value being outputted by the chunk. Throw in a custom output filter to parse the value further, and you've created a dynamic(-ish) title.

By the way, this is the custom getPagetitle snippet we use as output filter:

Due to recursive parsing of tags, it is needed to check the $input variable for a valid value, and stop doing things if it aint. After that, simply fetch the resource with the ID given, and return it's pagetitle.

The getResources snippet is actually quite easy when you know how to start. As everything though, it can be convenient to have someone point you in the right direction when starting something new.

What is getResources?

Some people call getResources the replacement for Ditto, and frankly, it is listed as an equivalent in the docs. But getResources is probably more flexible then that, especially when combined with other snippets such as getPage. This article will help you get started with a quick example of how to use getResources.

New for MODX 2.2: Articles!

As of MODX Revolution 2.2, you can also use the Articles plugin which is pretty much a one-click Blog install for MODX. Read more about Articles.

Requirements

Let's get going!

The getResources snippet takes a lot of different parameters as the documentation shows, but for now we'll only use a few of them. These are &tpl, &parents, &depth and &limit. MODX veterans (or at least anyone who has worked with snippets like Ditto and Wayfinder) will probably recognize what they do. In order, they specify a chunk to use as a template, the IDs of parent resources, the depth to search in and the number of resources to return.

This is my getResources call I place in the content of my category container page:

By doing this, you get all resources from within the resource it is being called from, only one level deep with a maximum of 10 resources being visible. The blogTpl chunk is as follows:

You can see we put each item in its own div with class blogPost, and create a link to our resource with the link tag. We're also using some output filters, for example "strtotime" and "date" to make nicely presented published dates. We also use a custom output filter, which is parsetags - one could just as easily use the toLinks snippet (part of tagLister) to create links to the tag detail pages. Furthermore we're also showing the count of comments, based on a thread identified by the parentid-resourceid - make sure that matches how you set up your comment threads in the Quip and QuipReply snippets!

Now, this was a real brief article - however there's many, many, many more to know about getResources - all of which you can find in the docs, and possible future follow-ups to this post.