Bob's Guides

MODX Templates

A MODX Template is essentially a blueprint for a web page on your site. It generally contains nothing but HTML code and MODX tags. Some Templates also contain JavaScript code. Think of it like the letterhead used by a business. The letterhead will contain the information the company wants to have on every letter. Like a web page, it will usually have a header and footer (and in some cases, a sidebar).

How MODX Processes a Page Request

When MODX receives a request for a web page, the first thing it does find the Resource associated with that URL (usually referred to as the "Current Resource") and get the template field of that resource. The template field contains the ID of the template to be used for the web page. Using that ID, MODX retrieves the Template from the datbase

The code of the Template is the starting point for every web page. The basic process MODX uses to render the page is relatively simple to describe. MODX takes the Template, replaces all the MODX tags in the Template, and sends it off to the browser. Before being sent to the browser, content in the Template might be altered slightly by any plugins that are triggered at various points in the process. The plugins (if any) usually make minor changes like changing the URL. For many web pages, no plugins are involved and it's just a matter of replacing the tags (technically called "parsing" the Template) and sending the finished page off to the browser.

This simple process gives MODX users tremendous freedom of expression. Templates can't contain raw PHP code, but beyond that, there are really no rules. Any valid HTML is permissible, all the MODX tags are optional, and the tags can be placed anywhere at all in the Template.

Of course, MODX also retrieves the Resource object (usually a Document) from the database before parsing the Template. The Resource object contains the main content of the Document and information about who created it, whether it's published or not, when it was last edited, etc. MODX needs that information to help it decide if the Document can be shown (depending on the security settings, whether the Document if published, etc.). It also needs the main content of the Document and often other information (like the title, longtitle, or any TVs involved) in order to replace the tags.

Once MODX determines that the Document can be shown to the current user (and many Documents are unprotected and can be shown to anyone as long as they are published), it begins replacing the tags. See this page for a summary of the MODX tag formats for both Evolution and Revolution. The process of replacing the tags goes like this:

• Chunk tags are replaced with the content of the named chunk
• Snippet tags are replaced with the return value from the named Snippet
• Template Variable tags are replaced with the value of the TV for the Current Resource
• Link tags are replaced with the URL specified in the tag
• System Setting tags are replaced by the value of the named System Setting
• Placeholder tags are replaced by the value of the named Placeholder
• Language tags are replaced by the appropriate language string from the MODX Lexicon

All of the above except Placeholder and Snippet tags simply look up values in the MODX database and use them for the replacement value. Snippets, of course, are pieces of PHP code, so the value used for the replacement depends entirely on the code of the Snippet — the replacement value is whatever is returned by the Snippet. Placeholders are temporary values, set by a Snippet or Plugin. MODX stores them in a temporary location and looks them up whenever a placeholder tag is processed.

Nested tags (that is, tags inside of other tags) are processed from the inside out. The inner tags are replaced before the surrounding tag is processed. Here's an example of a System Setting tag nested inside a Link tag:

    [[~[[++site_start]]]]

The inner tag, [[++site_start]] will be replaced by the value of the site_start System Setting, leaving the tag looking like this (assuming that the Resource ID of your home page is 1): [[~1]]. MODX will then process that Link tag to produce a url that might look like this: https://yoursite.com/home.html — a link to your Home Page. In the Template, we might see that tag used like this:

    <p>Here's a link to the <a href="[[~[[++site_start]]]]">Home Page</a></p>

If you decide to change the Home Page of your site to another page, all you need to do is set the site_start System Setting to the Resource ID of the new page and all your links will automatically point to that page. If you use Link tags for all internal links on your MODX web site, it will be much easier to maintain.

Creating and Editing a Template

These instructions are for MODX Revolution, but the process is similar in MODX Evolution. In Evolution, you would go to Elements | Manage Elements | Templates tab and click on the "New Template" link or the name of the Template you want to edit.

In Revolution, you can select the Elements tab on the left side of the Manager, right-click on the "Templates" folder and select "NewTemplate" or click on the Template you want to edit (under the Templates folder, which you may have to expand by clicking on it). In Revolution, you can also right-click on the Template you want to edit and select "Quick Update Template". That will open a popup window where you can edit the Template and save it without losing your place in the Manager.

Once you see the Create/Edit Template panel on the right, you can give a new Template a name, fill in the HTML code in the Template Code (html) field, and save the Template. That's all there is to it.

Example Template

Let's look at a minimal Template and see how it would be processed by the MODX Parser.

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    <html xmlns="https://www.w3.org/1999/xhtml">
    
    <head>
    <title>[[++site_name]] - [[*pagetitle]]</title>
    <base href="[[++site_url]]" />
    <link rel="stylesheet" href="[[*CssPath]]" type="text/css" />
    </head>
    <body>
    [[$header]]
    <div class="MainMenu">
        [[Wayfinder? &startId=`[[*id]]` ]]
    </div>
    <div class="StandardPage">
        <h2>[[*longtitle]]</h2>
        [[*content]]
    </div>

    [[$footer]]
    </body>
    </html>

When MODX recieved a request for a page using this Template, it would get the page, check its template field (which would contin the ID of this Template), and get the Template.

It would then begin replacing the tags. The first tag, [[*CssPath]] is optional, but an interesting trick. The tag refers to a Template Variable called "CssPath" which you would have to create and attach to this Template. The TV would contain the path to the CSS file you want to use for each individual Document. If you want the same CSS file for every Document using this Template, it's unnecessary, but sometimes it's handy to use different CSS for different pages. In this case, the tag would be replaced with the value of the Template Variable for the Current Resource.

As an aside, you could also use a Snippet instead of a TV for the CSS path. The Snippet could detect the user agent return a differnt path for each one. This would provide different CSS files for each type of user agent (e.g., a different CSS file for tablets or smart phones).

Next, MODX would replace the [[++site_name]] tag with the value of the site_name System Setting, then replace the [[*pagetitle]] tag with the value in the pagetitle field of the Current Resource. In the base href tag, the [[+site_url tag would be replaced with the value of the site_url System Setting.

since [[$header]] is a chunk tag, it would be replaced with the content of the "header" chunk.

The Wayfinder tag is a little more complicated. MODX would first replace the [[*id]] tag with the ID of the Current Resource (taken from the id field of the resource object). Then it would execute the Wayfinder Snippet, sending the ID as a property. Wayfinder would use that ID and create a whole menu containing all the children of the Current Resource and return it as a string. MODX would replace the whole Wayfinder tag with that menu.

The [[*longtitle]] tag would be replaced with the value of the longtitle field of the Current Resource and the [[*content]] tag would be replaced with the value of the content field of the Current Resource.

Finally, the [[$footer]] tag would be replaced by the content of the "footer" chunk.

With all the chunks replaced, MODX would then send the finished web page off to the browser for display.

Templates can be as simple or as complicated as you want them to be. They can contain any MODX tags and by using Template variables, Snippets, and different CSS files you can make the same Template look very different on different web pages.

Copyright © 2011-2025
Bob Ray