Bob's Guides

Getting Started with MODX

Before starting this section, you'll want to read the basic Introduction to MODX and how it works if you haven't done so already.

The MODX Manager is where you'll do most of the work on your site. The great thing about the Manager is that it is completely web based. You can work on your site from anywhere with any web browser. The Manager uses Ajax to make things relatively fast and smooth.

Getting Started

Once you have installed MODX, you can reach the manager by pointing your browser to https://yoursite.com/manager and logging in (where "yoursite.com" is the location of your MODX install). Once you log in, you'll be looking at the MODX Manager screen. Here you can change configuration details; add or edit web pages; create snippets, chunks, templates, template variables, and plugins; manage users and permissions; and much more. If you don't know what all that means, relax, it will all make sense eventually.

You can see the "front end" of your site, the site that regular users will see, by going to the same address but leaving off "/manager." (The MODX Manager is considered the "back end.") You can also see the "front end" by selecting View on the Site tab but there's a drawback to this. Because MODX knows you are logged in as a Manager, you won't necessarily see the site as a regular user would. This wouldn't be much of a problem now, but as your site grows more complex, this view might be very different from the one a Manager sees. If you want to review your changes as you work on a site, it's usually a good idea to open the "front end" in a different browser from the one you're using in the Manager. It's not enough just to use a different browser window because, in that case, MODX will still think you're a Manager as long as you're logged in to the Manager. If I'm editing a site in IE, for example, I'll open the "front end" in FireFox (or vice versa).

After installing MODX, your site will be just the default MODX home page (which uses the default template). You'll eventually replace it with your own site, but it's nice to have something there to see so you know the install went without a hitch. The links you see on the default MODX home page are not to places in your site, they're links to other MODX sites such as the MODX Resource Repository, the MODX forums, etc. They're just there as examples although some point to useful information about MODX.

NOTE: If you're using MODX Revolution, you can choose to install the MODX sample web site in the Package Management section of the Manager. The sample web site uses most of the main MODX snippets and a working blog. You can examine it (and modify it) to see how everything works. You can follow the instructions below to add your own content to that site, or you can create a separate, empty MODX site to try out the techniques on this page.

Log in to the MODX Manager as described above. On the left side of the Manager screen, you'll see the Resource tree for your site ("Resource" is short for "Web Resource"). There won't be much there, but it will grow as you add documents to the site. A document is the most common kind of resource in MODX and it generally holds the distinct content for a particular web page. Most documents are for displayable web pages but the word "document" is used intentionally in MODX because documents can play other roles. Some are just containers for other documents and are never seen by users. A few might be utility pages that you create to perform some chore like searching the site, displaying information about your server, or backing up all or part of the MODX database. On many sites, all the documents are for actual web pages. It depends on the complexity of your site, how much work you want to do, and your programming abilities.

Notice the little number to the right of each name in the Resource tree. This is the Resource Identifier (also called a Resource ID and formerly Document ID). It's a very important number because almost all references to resources in MODX are by the Resource ID. If you want to put a link to a document on any page in your site, a correct MODX link contains just the Resource ID. MODX will make sure that the correct document is served up even if its name changes, it's moved, or even if the site is moved to another domain and all the paths change.

Notice the toolbar at the top of the Resource tree. You can hover the mouse over the icons to see what they do. The one with the little arrow on the right will hide and restore the tree. This is useful if you're editing a document and would like a bigger space to work in.

It's a fact of life in MODX that there are multiple ways to accomplish almost any task. The toolbar above the Resource tree has an icon for creating a new document but there are several other ways to do the same thing. Try right-clicking on a document in the tree. You'll see a menu that lets you create a new document or change some of the settings of the document you right-clicked on. As usual, there are other ways to do this too.

On the right side of the Manager screen, if you've just installed MODX, you may also see some messages about MODX security and configuration that will disappear once you follow the advice they give. If you've installed MODX on your local machine, you may choose to ignore them, but on a public server you should clear them up before proceeding.

Notice the tabs at the the top of the Manager screen (the Manager Top Menu). Each one contains links to sections of the Manager where various tasks can be performed. Click on each of them and take a look. Don't be alarmed by how many settings there are. Most of the defaults will work fine for you for now.

If you are just playing around with MODX, you can continue to use the default home page and template. Add some new documents, change their settings and edit their content to see how MODX works. Even if you're porting an existing site to MODX, you'll want to go through this section to see how things work in MODX. It's a good idea to practice all the tasks involved in working on a MODX site before trying to plug in important content of your own.

You can create and delete documents to your heart's content. You'll notice that deleted documents still appear in the tree but with a line through them. They'll stay there in the "trash can" until you click on the little trash can icon and delete them permanently. When you're ready to create a real site, just create the documents you really want and delete all the ones you don't want. The only effect of this playing around is that you'll have bigger document ID numbers. This has to happen because every document ID is unique and can't be re-used. It doesn't really matter, though, because those numbers are just used internally by you and MODX and no user ever sees them.

If you don't know what a MODX template is, go back here for an explanation. The MODX default template is just an example of what a template looks like in MODX. You can modify it but it's probably better to create new templates for your own use and leave it for future reference. Let's take a look at the default template. In the MODX Manager:

For MODX Evolution:

1. Click on the Resources tab at the top of the page.
2. Select Manage Resources.
3. Select the Template tab on the right if not already selected.
4. Click on the default template on the right side.

For MODX Revolution:

1. Click on the Elements tab in the left panel.
2. Expand the Templates section by clicking on it.
3. Right-click on the BaseTemplate (which is the default Template).
4. Select Edit Template on the drop-down menu..

Before putting your own stuff in a page, take a look at some of the features in the MODX default template. Notice the square brackets with stars inside them:

MODX Evolution [*something*]

MODX Revolution [[*something]]

These are MODX Resource Tags. When MODX renders a page, it replaces the Resource Tags with the appropriate content (more about this later).

The ones contained here are standard resource fields that are available for any MODX document. When you create the document, you'll fill these in on the document creation screen. The most commonly used resource fields are pagetitle, longtitle, and content. You can also create your own custom resource fields (called Template Variables), but for now, we'll just talk about the standard ones. Look for the resource tags in the template. It's not a bad idea at this point to print out the default template so you can refer to it when you create your own. Note that like most of the references in MODX, resource field names are case-sensitive ("MyPage" is not the same as "myPage") so be careful to use the same case when creating and referring to them.

Notice in the default template how the pagetitle resource tag is used to set the page title (appears at the very top of the browser window). The longtitle resource tag is often used as the main heading for a page (often inside of <h2></h2> tags. The content resource tag is very important. It contains the document's actual content (what the user sees in the body of the web page). If this is unclear, it will make more sense after you create a document or two. It might help to look at the "front end" in another browser to see what MODX replaces them with. You can also right-click on the home document in the Resource tree and select Edit document. This will show you the document's resource fields although it will take you away from looking at the default template and you'll have to navigate your way back by following the numbered steps above.

You might also notice that, in the default template for MODX Evolution, the "content" resource tag has a pound sign after the first star. This means that users who are logged on and have the appropriate permissions can edit the content text using the MODX QuickEdit editor from the "front end" of the site. You'll see the QuickEdit button next to the content if you "View" the site while logged in to the MODX Manager. Another thing to look for in the default template is snippets which look like this:

[[something]]

They can also take this form:

MODX Evolution: [!something!]

MODX Revolution: [[!something]]

The exclamation point tells MODX to run the snippet uncached, which means that MODX runs the snippet each time the page is requested rather than getting the snippet's output from the MODX cache. This will slow down the page loads slightly, but it is necessary if the snippet will produce different results at different times.

You should see the Wayfinder snippet and the PoweredBy snippet. The Wayfinder snippet creates the menu at the side of the page and the PoweredBy snippet creates the "Powered by MODX" message in the footer.

By the way, there's nothing special about the term "BaseTemplate." It's just what that template happens to be called. You can change its name without causing any trouble.

Take a look at the site from the "front end" (when you are in the Modx Manager, we say that you're looking at the site from the "back end"). There are two ways to see the "front end" of the site. Although we advised against it above, for now, try selecting View on the Site tab in the MODX Manager.

In looking at the home page from the View "front end", you can see that MODX has replaced the Wayfinder snippet with a menu and the PoweredBy snippet with a message about MODX at the bottom of the page. Since you are logged in to the manager, if you are using MODX Evolution you should also see a little QuickEdit button next to the page content when you View the page. (Users who are not logged in won't see that.) When you look at the "front end" through View, you see the little edit button next to the page content. Earlier, we mentioned the pound sign next to the "content" resource tag in the default template. That's what tells MODX to put the QuickEdit button there. In the upper left corner of the page, you should also see a little menu that provides yet another way to change some of the page's settings. The Go drop-down menu there will take you back to the "back end," the MODX Manager.

Now it's time to add some content to the site by creating a new page.

Creating a New Document

Now, let's create a new document that will be used in a new web page. Remember that a web page is what the user sees in his or her browser, a document contains the unique content of that page and information about that page. First, we'll create a new document and then we'll add some content to it. In the MODX Manager, right-click on the MODX home page in the Resource tree on the left side of the screen and select Create | Create a Document Here. The Create/Edit Resource panel should open on the right side of the screen (the heading will be New Document). Notice that the page has three tabs, Document, Settings, and Resource Groups.

There is also a Template Variables tab that will appear between Settings and Resource Groups if any Template Variables are attached to the Template used by the document.

We'll start on the Document tab. Note that if you scroll down, the tabs will disappear but they're still there if you scroll back up.

Fill in:

• "New Document" in the Title field
• "My New Document" in the Long Title field
• "new-document" in the Resource Alias field
• "New Document" in the Menu Title field.

You can use other terms in the fields if you like. Documents in MODX are always referred to by Resource ID numbers so the content of these fields is completely up to you.

Use the drop-down menu next to Uses Template to set the template to either the default template (BaseTemplate) or (if you created a new template) to the one you created.

Now, if you are using MODX Evolution, click on the Settings tab and make sure that the Published? checkbox is checked. If you're using MODX Revolution, the Published checkbox will be on the Document tab. If the checkbox is not checked, your document won't show up in the "front end" of the site. This is handy for working on pages that aren't yet ready for publication.

Note for future reference that you can set whether the Published checkbox is checked by default when you create a new document. In MODX Evolution, this is set in the Tools | Configuration section near the bottom of the Site tab. In MODX Revolution, it's found in the System Settings grid (System | System Settings) — it is controlled by the publish_default System Setting. If you type 'default' in the search box at the upper right of the System Settings grid, you can see all of the default System Settings.

Notice also (on the Settings tab) that you can set the Publish date and the Unpublish date by clicking on the little calendar icon next to those fields. These fields are only used if you want to publish or unpublish a document on a future date. MODX will automatically publish the document on the Publish date and unpublish it on the Unpublish date. If these are left blank, the document will be published or not depending on the Published checkbox. Don't change any of the other fields but take a look at them for future reference.

On the right, notice that there is one scroll bar for the document and, unless you have a very high-resolution monitor, another for the browser window. You often have to use both to edit a document. Scroll down to expose the Content window. This window will be visible no matter which tab you are on. The text you enter in the Content field will appear wherever you put the following tag in your template:

MODX Evolution: [*content*]

MODX Revolution: [[*content]]

Enter some text. Notice that if the Rich Text checkbox on the Settings tab is checked and an editor (e.g., TinyMCE) is installed, you can use the WYSIWYG editor to style the page.

If you prefer working in raw HTML (and I recommend it if you know how), uncheck the Rich Text checkbox. There is an HTML button on the Rich Text editor that let's you see and edit the raw HTML, but using it can cause problems when the editor tries to be intelligent in figuring out what you want and changes some of your code when the page is saved. Unchecking the Rich Text checkbox will prevent this. Changing the setting of the Rich Text checkbox won't take effect until you save the page.

The Save button at the top of the page does just what it says.

When you've finished entering your text, Click on Save. Your new document should appear in the Resource tree at the left of the screen. Notice the number in parentheses next to the document. This is the document's Resource identifier (or Resource ID) we talked about earlier. This is the number that MODX uses to refer to the document. It will never change and you should always refer to the page by this number in links or other references since it will be good even if the page is moved in the site, the site moves to a new domain, or the document's pagetitle changes.

Adding the New Document to the Menu

Take a look at your document from the "front end" using one of the methods described above. If you have the Wayfinder snippet call in your template, you should see that the new document is already there in the menu. Is this a great CMS or what? Generally, every new page will automatically show up in a properly configured Wayfinder menu as long as it's published and the show in menu checkbox is checked. The only exception to this is a page that has permissions set to deny certain users access to the page, but that's a topic for another time. Notice that the reference in the menu is what you entered in the Menu Title field when you created the document. As long as all your links refer to the Resource ID, you can change the Title, Longtitle, and Menu Title fields as often as you like. In fact, you can change any of the fields by right-clicking on the document in the Resource tree and selecting Edit Resource.

When you were looking at the Settings tab when creating your new document, you may have noticed the Menu Index field. This allows you to set the order of menu items in any Wayfinder menu. An item with a Menu Index of 0 will show up at the top of its menu. If you want a document to always be listed as the last item in any menu, you can give it a Menu Index of 999. You can change a document's Menu index any time you want to move it up or down in the menu. In MODX Revolution, you can also drag resources around in the Resource tree to set their menu order. If you do that, any Menu Index numbers you have set will be changed. The Menu Indexes for the Resources will be renumbered based on their locations in the tree.

What Next?

Create some more pages (documents), and play around until you're comfortable with creating, configuring, and saving pages. You can edit an existing document (or change its settings) by right clicking on the document in the tree and selecting Edit.

To put a link to another document on a page if you are using the Rich text editor, you can just highlight the text for the link and click on the link icon in the editor toolbar. (If you are using the default TinyMCE editor, it looks like a chain link.) For the URL of the link, simply put a link tag like one of the following in the form field (use the target document's actual document ID instead of 12):

MODX Evolution: [~12~]

MODX Revolution: [[~12]]

If you are editing raw HTML, put the usual HREF statement but put a tag like one of the ones above inside the quotation marks. MODX will handle the rest.

To return to the main MODX page, click here.

Copyright © 2011-2025
Bob Ray