Bob's Guides

The MODX Content Management System

MODX is a content management system that helps you create superlative websites. There are two key benefits to MODX. First, it makes websites easy for you and others you designate as site admins to maintain. Second, once you get used to it, it allows you to create very complex websites in a very short time. Things that would take many lines of code for you to do yourself can often be accomplished with a line or two in MODX. Of course there are many other benefits as well, but we'll get to those later.

Why MODX?

There are other content management systems that allow you to create a website rapidly and maintain it easily, but they tend to restrict you in many ways. Working with such a CMS can make you feel like you're bound up in duct tape. MODX, on the other hand, is flexible and open. You can extend it easily in almost any direction and create exactly the website you want with no compromises. For this reason, MODX is often described as a "content management framework" rather than a "content management system." Because of the power and flexibility of MODX, it can be a little hard to get started but, once you get the hang of it, it's amazingly easy to use.

The best reason for using MODX is the total freedom it allows you in designing your website. A MODX Template is simply HTML code with optional MODX tags in it. MODX will replace the tags with whatever they represent. You're not required to use any tags and there are no rules whatsoever about how the Template is organized. Any content that you want to show on a page can be placed anywhere in the Template. Where it shows up and how it looks will be governed only by the CSS rules you create for it. MODX will not interfere with that process in any way except to make sure there is no raw PHP code in the page. All PHP code must be placed in Snippets or Plugins. This makes the site more secure and helps you separate content from presentation.

You may be anxious to install MODX, but first, you might want to know how MODX works and what features would make you want to install it in the first place. If you like to jump right into the action, you can go to Installing MODX to install MODX and start playing.

How does MODX work?

As with many other content management systems, MODX stores the data for your web pages in a database. When a user visits one of your pages, MODX goes to the database, gets the information, assembles it, and sends it off to the user's browser for display. This all happens behind the scenes. Many MODX users create sites without ever dealing with the database or the process of saving and retrieving the information. To really make MODX sing, however, you'll eventually want to learn about how some of the behind-the-scenes processes work.

Extending the MODX framework are, among other things, Templates, Snippets, Chunks, Template Variables, and Plugins. They're much simpler than they may sound, and we'll get to those in a minute, but first a little bit about the MODX Manager.

Getting Started

The MODX Manager is where you work on your website. One of the great things about MODX is that you can work on your site from anywhere you have a web connection. The Manager is a tool stored at your site and, once you log in, you can add content, edit existing content, and do almost any task that you could do at home. Everything you need is in the Manager so the only thing you need on the computer you connect from is a web browser. If the Manager is in its default location (you can rename it, and doing that makes your site more secure), you can reach the Manager by entering the following URL in your browser's address bar:

https://yoursite.com/manager

In the Manager, you can edit your pages in a rich text html editor or, if you prefer, you can edit the raw html of each page. You can upload images, control who gets to see and/or edit each page, add new pages, re-organize your menu, create users and much, much more. Go to Getting Started with MODX to learn more about MODX and using the MODX Manager. If you're new to MODX, however, it's a good idea to finish reading this page before going to the Getting Started link.

In the following sections, we'll cover two basic building blocks for a MODX web page: Resources and Elements

Resources

Resources (short for Web Resources) are rows of data in the MODX database that generally contain information about a particular web page. Modx Resources are Documents, though Weblinks, Symlinks, and Static Resources, are also resources, but that's a more advanced topic, so we'll skip it for now and concentrate on Documents. Most of the time in MODX when you see the word Resource, it refers to a Document and represents information for a single web page.

Documents

A web page, in MODX, is the finished product that MODX sends off to the user's browser when that page is requested. A MODX Document, on the other hand, is the heart of that web page and contains the content that appears only on that page (like the paragraph you are reading now) as well as various pieces of information about that Resource (e.g., who created it, when it was last edited, etc.). In MODX, Documents are classified as Web Resources (Resources for short). Templates, Chunks, Snippets, Template Variables, and Plugins are classified as Content Elements (Elements for short) — more on those in a bit.

Because MODX is pre-processing requests for pages, it can do a lot of tricks with the page before it is sent to the browser like inserting a menu, breadcrumbs, recent blog posts, or news items; showing a random photo; filling in a standard header, logo, or footer; and adding boilerplate content at various places on the page.

When you create a Document in the MODX Manager, you can specify whether you want it to appear on the website or remain hidden, shown in menus (or not), how it will be referred to in any menu, where it will be placed in the menu, who can see it, who can edit it, the dates you want it to appear and disappear from the site, and other details about the page. Many of these page attributes are optional so, if you just want to create a page and let everyone see it, you can ignore most of these settings and just type in the content of the page. Go here to learn more about creating and editing MODX Documents.

Elements

MODX Content Elements (almost always referred to as just "Elements") include Templates, Chunks, Snippets, Plugins, and Template Variables. In the following sections, we'll give a brief overview of these Elements. At the end of each section there is a link to a page with more detail about the Element.

Templates

A Template in MODX is just a place to put the stuff that you want on every page or a subset of pages. Typically, a Template will contain the banner that goes at the top of each page, the footer that goes at the bottom, a menu for all or part of your site, and any other content that should appear on every page that uses the Template. You can have as many Templates as you like, but many sites just use a single one so that all the pages have the same look, layout, and style. Sometimes, people create special Templates for things like upload pages, blog pages, photo gallery pages, etc. You might also have a special Template for your home page, although in many cases it's not necessary.

You might think of a Template like the letterhead used by a business. The letterhead will almost always have a standard header and might also have a footer and sometimes a sidebar. When the business sends a letter, the content of the letter appears inside the standard elements of the letterhead. When you create a typical MODX Document, you type in the content and save it. In the Template for that Document, you put the MODX content tag, where you want that content to appear. When a user visits the page, MODX gets the Template, replaces the content tag with the actual page content, and sends the page off to the user's browser for display. The content tag looks like this:

[[*content]]

You can also put some of the other information from the Document into the Template if you like, such as the title, longtitle, publication date, author, etc. These are resource fields that you type in when you create the Document in the MODX Manager. They're stored with the Document in the database. You can even create custom resource fields called Template Variables to hold extra information related to the Document and place those in the Template as well.

On this page, for example, the Template contains the page title (what you see at the very top of your browser window). It's generated from the site name System Setting and from the title of this Document: ("The MODX CMS"). The Template also contains tags referring to the header and footer, and the main heading you see at the top of the page, which is generated automatically from the Document's longtitle. The Document's content is just the subheads and paragraphs of text on the page.

When I create a new page for this site (by creating a new Document). I just tell MODX I want a new Document, type in the page content, and fill in the resource fields. The page appears automatically in the menu and the title and main heading are generated automatically by MODX. For the main heading at the top of this page, the Template would have the following:

[[*longtitle]]

When the page is requested by a browser, MODX sees that reference, gets the longtitle field of the Document, and replaces that tag with it. As another example, if you want to put the Document ID number of a page on that page, you could add this tag to the Template:

[[*id]]

You can go to this link for more information on resource fields and how to use them.

Chunks

What if you have some content that you want on many pages but not all of them, and you want it in different places on different pages? That's where Chunks come in. A Chunk is just a piece of text or html code that you can place anywhere on any page. It can contain text, images, links, Snippets, JavaScript, or anything else that can go on a web page. You create the Chunk in the MODX Manager and simply put a reference to it on any page in the position where you want it to appear.

Say you want to put a paragraph of text on some of your pages. You just create a Chunk. Let's call it MyChunk and put the following text in it:

<p>This will appear wherever I want it to.</p>

Then, whenever you want that text to appear in a page, you simply put a Chunk tag at the spot where you want it:

[[$MyChunk]]

Chunks can be placed in headers, footers, Templates, or in the content of a Document. Go to the MODX Chunks page for more information. Chunks can contain Snippets, but they don't have to.

Snippets

What if you want to have some dynamic content on a page? Maybe you'd like to read a list of files from a particular directory, sort them alphabetically, and put them on the page as links. Files are always being added to the directory, so you can't just create a file list and put it on the page (well, you could, but then you'd have to edit the page every time someone uploaded a new file). You'd much rather generate the file list dynamically from the actual contents of the directory. That way it would always be up-to-date. To do this, you'd write a bit of PHP code to read the directory and print out the HTML code for the list, put that code in a Snippet, and just put a reference to the Snippet on the page where you want the file list to appear with a line like the following:

[[MyFileListSnippet]]

If you need to tell your Snippet something about how to operate, you can add properties in the Snippet tag like this:

[[MyFileListSnippet? &sortOrder=`ascending` &fileDirectory=`assets/mydir/`]]

The ampersands indicate MODX properties in a tag. Properties are just pieces of information that can be sent to a Snippet. Properties can be optional or required. These two tell the Snippet that you want an ascending sort order and that the files to be displayed are in the "assets/mydir" directory. In the Snippet's PHP code, these can then be accessed as regular PHP variables ( $sortOrder and $fileDirectory ).

Many Snippets also allow tpl properties which generally contain the names of Tpl Chunks used to format and style the Snippet's output. This lets you specify a different Tpl Chunk for the Snippet to use instead of the default one.

Go here to learn more about Snippet properties.

If you don't know PHP, don't despair. MODX already has a number of built-in Snippets that can do a lot of what you want. New Snippets are being created by the MODX developers community all the time. The Wayfinder Snippet creates menus like the one at the top of this page. The Breadcrumb Snippet creates breadcrumb-style navigation lines. The getResources Snippet In Revolution, you can manage image galleries with the several different Gallery extras. The SPForm Snippet creates a simple contact form like the one on this site's Contact Us page.

The FormIt Snippet creates more complex forms that can be used to register users, collect data, and store the data in the MODX database. Tasks that would take many lines of code on a regular website can very often be done with a single Snippet tag in MODX.

To learn more about Snippets, you can visit the Snippets page.

Chunk or Snippet - Which do I use?

Chunks and Snippets are both used to insert content in a web page. For new users it can be confusing to figure out which one to use when. There's a pretty simple rule of thumb, however, for making this decision. If you want to insert a piece of content on a number of web pages, the content contains no PHP code, and you don't want to put that content in the Template, you want a Chunk. For example, you might want a disclaimer telling users that you won't be responsible for damage caused by following the advice on a page. You don't want this in the Template because it won't appear on every page, and it will appear in different places on different pages. A Chunk is perfect for this. If you change your mind about how to word the disclaimer, you can just edit the Chunk and the text will change on every page that contains that Chunk.

Chunks can't contain PHP code, only HTML and the usual items you'd put on a MODX web page. Chunks can contain flash graphics, JavaScript, images, tables, paragraphs of text, Snippet tags, and anything else you'd put on a standard MODX web page. When you create a Chunk you can place the Chunk tag like this on any page:

[[$MyChunk]]

When MODX sees the Chunk tag, it simply gets the contents of the Chunk and plugs it in where it found the Chunk tag. Chunks usually load faster than Snippets because MODX doesn't have to work as hard to interpret them.

The header and footer of this page are actually Chunks that I inserted into the Template. I could have put their content directly into the Template without using Chunks, but having them in separate Chunks means I can edit them without worrying about messing up the rest of the Template.

Go to Creating and Using Chunks to learn more about Chunks.

A Snippet, on the other hand, is for when you want dynamic rather than static content. It might contain PHP code or Javascript code (or both) and it creates content "on the fly" to be inserted into the page. The drop-down menu at the top of this page is created by the built-in MODX Wayfinder Snippet. The output looks a little different on every page. The Wayfinder Snippet uses PHP code to figure out where you are in the site and generates the appropriate HTML to be output. Go to Creating and Using Snippets to learn more.

Links

You will often want to put a link on a page that links to another Document at your site. MODX makes this really easy by providing a link tag. Anywhere you want the URL to a MODX page on your site, just put a link tag like the following where ## is the Resource ID number found in parentheses next to the Document name in the tree at the left of the left side of the MODX Manager:

[[~##]]

So in raw HTML, a link to Document 12 will look like this:

[[~12]]

If you are using a Rich Text Editor (e.g., TinyMCE) to edit your page, you can also highlight the link text (in this case "My other page"), click on the hyperlink icon (usually a sideways 8, chain link, or infinity sign) and enter:

[[~12]]

for the URL. The link code will be inserted automatically. Note that the hyperlink icon won't be active until after you highlight some text.

Plugins

Plugins are another advanced topic and, again, many MODX users will never create one. Plugins are used to interrupt the processing of the MODX engine and add custom functions. There are a number of hooks into the MODX engine that let you perform just about any kind of operation at key points in the processing. You can, for example, have access to a Document's content just before it's rendered as a web page. You could translate it, emphasize keywords, turn some items into hyperlinks, etc. You can do anything you can write code for. You can also process Documents before they're saved, process a user's information during the process of logging in or do any number of other transformations. The beauty of Plugins is that they allow you to put custom processing in place without hacking the MODX core so your work won't be affected by upgrading to newer versions of MODX.

Go here for more information on Plugins.

Template Variables (TVs)

A Template Variable (TV) is simply an extra resource field that you create yourself. Although you see Template Variables and enter their values when editing a Resource, they actually belong to Templates. When you edit a particular Resource, you'll see the Template Variables attached to the Template used by the Resource. A TV can have a different value for each Resource and TVs can contain tags for other MODX Elements.

The value of a Template Variable can be displayed on a web page with the following tag:

[[*TvName]]

MODX would replace the tag with the value of the named TV for the current page.

We've only scratched the surface of Template Variables here. To learn more about them, go to the Template Variables page.

Where Do I Put My Files

MODX is very flexible about file locations. Generally, you can put your own files anywhere you want as long as you remember where they are, but it's recommended that you place them under the assets/ directory. For typical locations, look at the File Locations page.

Copyright © 2011-2024
Bob Ray