MODX Newbie FAQ

If you don't find an answer here, ask for help in the appropriate section of the MODX Forums. If they might have a bearing on your problem, be sure to include your browser version, MODX version, hosting service, Apache version, PHP version, and MySQL version.


Click on a question to expand the answer

Show All      Hide All

What's the best way to search for information about MODX?

In general, you can find a lot of information through Google if you just include "modx" in your search string. Let's say you want to know about MODX plugins. You could do a search for: modx plugins. To search the MODX Wiki for information on plugins, you can Google: modx wiki plugins. To search for information on MODX Revolution installation, you can Google: modx revolution installation.

The MODX Forums are a fantastic resource. Unfortunately, the Forum search itself may not get you what you want. You can always Google modx searchterm(s) forums, but the absolutely best way to search the MODX Forums is with the custom FireFox search add-on described here.

Here's another way of doing the same thing:
search_term site:.modxcms.com/forums/ -'printpage' -'wap2'

For information on a particular MODX Revolution add-on component, Google:
modx revolution component_name documentation

Do I have to pay anything to use MODX?

Absolutely not. You will have to pay for a domain name and a hosting service, but MODX itself is free.

Is there a Fantastico script for installing MODX?

At present, no, but MODX is not particularly difficult to install. For the most part, you just copy the MODX files to the server and run the MODX install script. Look here to see the MODX installation guide.

Bluehost.com provides a SimpleScripts install for MODX that is very fast and reliable. It normally installs the most current stable version of MODX and will also upgrade your site.

Where can I get the latest stable version of MODX?

go here to get the latest stable release.

The installation instructions refer to an "archive" file. What is that?

It's just the compressed file you downloaded as the first step of the install procedure. If you are using Windows or Mac, it should be a .zip file. For Unix, it will be a tar.gz file.

The installation instructions refer to the "root" directory. What is that?

The root directory is the highest-level directory on your server that can be accessed by a web browser. On a remote server, it's often called "public_html."

If you are using XAMPP or any other local version of Apache, the root is usually the htdocs directory (on Windows with XAMPP, for example, it's often C:\Program files\xampp\htdocs).

In Windows Vista, many users install XAMPP to the C:\xampp directory -- in that case it would be C:\xampp\htdocs.

Do the files have to go in the root directory?

No, they can go anywhere on your server as long as they can be accessed by a web browser.

If you will have more than one web site on your server, you'll probably want them just below the root (e.g. public_html/my_site, and public_html/my_othersite).

The instructions say I should change the permissions on some files and directories. How do I do that?

If you have direct access to the computer, you can use the Unix chmod command.

If it's a remote machine, you can change permissions by going to cPanel (or the equivalent) at your host and clicking on "File Manager." In File Manager, you navigate to the file or directory you want to change (your site will normally be under public_html). You'll see the permission numbers on the right as you go. When you get to the target file or directory, click on its name, then on "change permissions."

You can also change permissions from within many FTP programs, usually either by right-clicking on the file, or by selecting it and clicking on a "permissions" icon.

Should I install MODX locally or on a remote server?

It's up to you. If you install locally, you will need a server such as Apache or IIS on your local machine and MySQL. A complete, self-installing, Apache server/MySQL package is available for most platforms using XAMPP. You can get XAMPP here.

On a localhost install, you can edit files somewhat faster and people can't see your mistakes, but you'll eventually have to move the site to a remote server so others can see it and this involves several steps including dumping your local MODX database using PhpMyAdmin.

Look here to see the steps involved.

Where can I get a server that will run on my local Windows machine?

Although some versions of Windows come with the IIS server, many MODX users find XAMPP to be more MODX-friendly.

Is there a server for Mac OS X?

Yes. You can find XAMPP for the Mac here, but Mac users I know tend to prefer MAMP.

How about a linux version of XAMPP?

Yes, there is now a linux version of XAMPP. Look here for the linux version (formerly called LAMPP).

I have MODX installed: Now what?

After reading the overview of MODX here, see this site's Getting Started with MODX page here.

Where do my files/documents/pages go?

In MODX, you usually enter the content of new pages in a form in the MODX Manager. MODX saves the content in a database and inserts it into your web pages when they are requested by the user's browser.

Go here for more information about the process and here for more information about how to create new documents.

When I try to install MODX, I get a message telling me that the connection to the database failed. What does that mean?

First, you need to create an empty database for MODX to use. Usually this is done using PhpMyAdmin. If you are installing MODX on your local machine, you can usually run it with https://localhost/phpmyadmin, if on a remote host, look for it on your control panel.

If you have already created the database, check your config.inc.php file in the manager/includes directory to make sure the settings for the database at the top of that file are correct.

It says "My MODX Site" at the top of every page when I preview my site. How do I change that?

In the Evolution Manager, go to Tools | Configuration | websitename | Site tab and change the setting for "Site Name." Don't forget click on "Save." For MODX Revolution, go to System | System Settings, find the site_name system setting and change its value. Note that this setting is placed in the template using the tag [(site_name)] for MODX Evolution and [[++site_name]] for MODX Revolution. You can use it anywhere on a page so that if you change the site name, it will change automatically everywhere in the site.

The "Create/Edit Resource" panel has a lot of fields. Do I need to fill in all of them?

No, you can leave many of them blank. For most documents, you'll want to fill in the Title (appears at the top of the browser window), the Longtitle (often used as the main heading of the page), the Alias (appears in the browser's address window), the Menu alias (how the document will appear in the menu), and the content window (the body text you want to appear on the page). You'll also want to set the Published checkbox and the Show in Menu checkbox.

What's the difference between the "Published" and "Show in Menu" checkboxes?

When the Published checkbox is checked, your document is live and accessible on your site. If the document is not published, you can still see it when logged into the manager, but it will not be available to regular visitors to the site.

The Show in Menu checkbox just sets a flag that the Wayfinder snippet (and other snippets) can use to decide whether or not to show the document in menus.

How do I get to the MODX Manager?

The MODX Manager (where you will do almost all the work on your site) is accessed by typing yoursite.com/manager in your browser's access window (replace yoursite.com with the actual name of your site). You should set a bookmark for it once you get there.

You'll see the manager log in page and you'll need to enter the username and password you created during the install. Don't forget to write down the password during the install.

The default initial username is "admin" but you should change it to something else to make the site more secure.

How should I organize my site?

It's entirely up to you, but it's a good idea to plan your site well before creating your documents. It will help you find your documents when the site gets to be large and complicated and you will probably use the Wayfinder snippet to create your menus and it will use the site's organization in the design of the menus.

Most MODX sites are laid out in a hierarchical tree just like any other web site (also like the directory structure on your hard drive).

Once I've created a new web page, how can I preview it?

You can preview pages by clicking on Preview on the Site tab in the MODX Manager.

If you have designated the page as Published, you can also navigate to it in your browser by putting the full URL of the page name in the browser's address bar or through a menu at your site (if you've created one). If you're logged on as a Manager, you can see the page that way even if it's not published. You can also see a page by selecting the Preview tab of the Create/edit document window.

How should I make links to the documents at my site?

All links in MODX should be made using a link tag. A link tag looks like this:

MODX Evolution: [~##~]
MODX Evolution: [[~##]]

Where ## is the Resource ID of the document you want to link to. (The Resource ID is the number in parentheses next to the document title in the tree on the left side of the MODX Manager.) A link to document 12 would look like this:

MODX Evolution: <a href="[~12~]">Link to document 12</a>
MODX Revolution: <a href="[[~12]]">Link to document 12</a>

If you'd like a fully qualified link for SEO purposes, you can use this variation:

MODX Evolution: <a href="[(site_url)][~12~]">Link to document 12</a>
MODX Revolution: <a href="[[++site_url]][[~12]]">Link to document 12</a>

What does it mean for a document to be "Published"?

When you create or edit a document in the MODX Manager, there is a Published checkbox. If you check it, visitors to your site will see the page, if you don't, they won't see it. This allows you to work on pages until you like how they look before publishing them.

You can also remove pages, temporarily or permanently, at any time by unchecking the checkbox.

MODX also gives you the option of setting a published date and/or an unpublished date for a document.

Documents with dates set will automatically appear on the site on their published date and disappear on their unpublished date.

Go here for more information about creating/editing documents and the various document settings.

What is a template?

A template is the outline for a document, much like the letterhead that companies use for business letters. It usually contains all the information that you want to appear on a number of web pages at your site such as headers, footers, menus, sidebars, etc.

Templates are discussed in more detail here and here.

What is a chunk?

A chunk is just a piece of content that MODX will plug in wherever you put a chunk tag. Chunks can contain anything you'd ordinarily put on a web page (images, text, HTML, JavaScript, etc.), but not PHP code. Go here to learn more about creating and using chunks.

What is a chunk tag?

A chunk tag is just a tag (or marker) in a MODX document that tells MODX that you want it to stick the contents of the chunk there. A chunk tag looks like this:

MODX Evolution: {{MyChunkName}}
MODX Revolution: [[$MyChunkName]]

Chunks are discussed in more detail here.

What is a snippet?

A snippet is a piece of code that MODX uses to insert content into a page. The snippet itself doesn't go in the document. Instead, you place a snippet "tag" on the page.

When MODX sees the snippet tag, it finds the snippet, has it generate the output, and puts that output on the page in place of the snippet tag.

Go here to learn more about snippets.

What is a "snippet tag"?

A snippet tag is just a tag (or marker) in a MODX document that tells MODX that you want the output of the snippet there.

A snippet tag looks like this:

[[SnippetNamee? &property1=`something` &property2=`somethingElse`]]

Snippets are discussed in more detail here and here.

Why isn't my snippet tag working?

There are four mistakes that account for 99% of the failed snippet tags:

1. Snippet names and property names are case-sensitive. Make sure you spelled your snippet name correctly. "startID" will not work if "startId" is expected.

2. Snippet properties must be enclosed in backticks, not single quotes. The backtick character is usually on the ~ key.

3. Each property sent in a snippet tag must have an ampersand character in front of it. These are easy to forget.

4. There should be no spaces around the equals signs in a snippet tag.

When do I use a Snippet and when do I use Chunks?

The basic rule is that chunks are for static content and snippets are for dynamic content.

Another way of putting it is to say that chunks can contain only HTML code (no PHP), etc.).

If you have something you want to appear on many pages and it can be expressed without PHP code (including links, images, anchor tags, JavaScript, etc.), you want a chunk.

If you need to generate something dynamically using code when the page is requested, you want a snippet. Note that there are many built-in snippets you can use in MODX without knowing anything about PHP or Javascript (though learning a little PHP will certainly help you get the most out of MODX).

What is a plugin?

A plugin is a bit of PHP code that extends MODX itself. Plugins operate behind the scenes at various points in the operation of MODX. A plugin is attached to a particular MODX System Event. When that event occurs, MODX transfers control to the plugin. When the plugin is done executing, it transfers control back to MODX. There is more information on plugins here.

Why does MODX keep taking me to my home page?

MODX automatically sets the default "page not found" target to whatever is designated as the site start page in Tools | Configuration. You can change this behavior, but that's how it's set at first.

That means that with the default installation, any time you click on a link and find yourself on your home page (or click on a link on the home page and don't go anywhere), it's just MODX's way of telling you that it can't find the page in the link or menu. If it's just one or two links that do this, it's likely caused by a typo in the link. If it happens with all links, it's more likely a problem with the rewrite rules in .htaccess.

MODX can't find my CSS files and/or images. Why?

Be sure you have this code in the <head> section of all your templates:

Evolution:
<base href="[(site_url)]" />

Revolution:
<base href="[[++site_url]]" />

I can't save some things in the Manager. When I try to save (happens most often with templates and snippets), MODX freaks out. What's wrong?

This is almost always a mod_security problem, especially if some things save and others don't. If your host has mod_security turned on, it prevents MODX from saving "suspicious" code to the database. Look here for more information on making the problem go away.

I get an error message relating to my /tmp directory. What does that mean?

By default session data is saved to the /tmp directory. Your host may have changed the path to that directory or changed the permissions on the directory so it can't be written to.

I created a new user but every time the user tries to save a document, this error appears: "You do not have permission to create or move a Resource here! Please choose another location." I swear I have the role set correctly. What gives?

Almost every MODX user runs into this eventually. There's a setting in Tools | Configuration | (User tab) called "Allow Root". By default, it's set to No, which means that, except for the super-admin (created at install), no one can save documents in the root of the site. Set it to Yes or inform your users that they can't create pages there.

Why don't my changes show up on the site?

MODX caches things to make pages load faster. Whenever you don't see a change you've made, you should clear the MODX cache (Site | Clear Cache) and also your browser cache. In some cases, you may also need to clear the cookies in your browser (note that this may mean you'll have to log in to the Manager again).

I see references to static and dynamic content. What does that mean?

Static content is just content that doesn't change. It's the same from visit to visit and it's the same no matter who is viewing the page. You might edit a document to change it's content, but that's still considered static content since, once you save it, it doesn't change.

Dynamic content, is content that changes. For example, you might greet the user by name when he or she logs on to the site or you might have a page that contains a directory listing of downloadable files that is generated "on-the-fly" from the contents of the download directory. These are examples of dynamic content.

The MODX cache: what is it?

The cache (pronounced "cash") is just a temporary storage area that MODX uses to store frequently used information.

When MODX renders a document, it has often has to perform a number of tasks behind the scenes before the document is sent to the browser. When a document is marked as "Cacheable," MODX stores the result in the cache so that the next time the document is requested, it can serve up the cached version without performing all the background operations.

Go here to learn more about the MODX cache.

When should I use the cache?

Generally, you should designate a document as cached when the content of the document won't change unless you edit it yourself. That way, the page will take less time to load.

What if a snippet on the page produces information that changes every time the page is visited?

MODX has the option of letting you call the snippet as uncached in a cached page. That way, MODX can cache the rest of the page and fill in the results produced by the snippet every time the page is called.

To tell MODX to call the snippet uncached, use the following form for the snippet tag (the exclamation marks are the only difference): [[!SnippetName &property1=`something` &property2=`somethingElse`]].

Where do .CSS files go?

There is no specific location for .css files in MODX, although there are some common places to look for them. You will sometimes find template .css files in the assets/templates/templatename folder. Similarly, .css files for specific snippets can often be found in the /assets/snippets/snippetname folder.

For convenience, some people put .css files in an assets/css folder. For performance, others put .css files in the root MODX folder (where index.php lives). If you create your own .css file, it's up to you where it goes.

How do you do menus in MODX?

Some people create their own menus using PHP code, but the majority of MODX users use the Wayfinder snippet. Wayfinder generates a menu automatically from the contents of your site. Wayfinder is marvelously configurable and its menus can be presented in just about any style you can think of. When you add a new document (page) to your site, Wayfinder will automatically include it in the menu.

The two menus on the right side of this page are each generated by a single line of code (a Wayfinder snippet tag), written a long time ago. As the site grows, they automatically include the new documents.

What can I edit and what should I leave alone?

Once MODX is installed and working, you won't normally edit any of the actual files at the site. You may add files when you install an add-on component, but most of the work on your site will be done in the MODX Manager where you can create and edit content, templates, chunks, etc. This creating/editing will change the contents of the MODX database, but it won't change any actual files on your site.

If you are good at PHP, you may decide to hack the MODX code or the code of specific snippets to get particular effects you want, but this will interfere with upgrading to new versions of MODX and very sophisticated MODX sites can be created with no hacking at all.

How do I upload a finished local project to a live remote server?

Complete instructions on moving a localhost MODX site to a remote server can be found here.

I have some data in a database that I'd like to access on my MODX site. What's the best way to do this?

If the data is in a MySQL database, you can just do the standard export and import it into the MODX database (using PhppMyAdmin for both). If not, you can export it to a CSV file using whatever tool you have in the database program and then import it into the MODX database using PhpMyAdmin.

Once it's in the MODX database, you can access the data with the MODX DBAPI, usually in a snippet.

Why can't I upload big files to my site?

For Evolution, go to Tools -> Configuration -> File Manager tab and check out the value for Maximum Upload Size.

For Revolution, go to System -> System Settings and check the value of upload_maxsize.

I'm blocked and/or I forgot my password. What now?

If the "Forgot Password" email on the login page doesn't work, there's another way in. Log in to your host's cPanel (or the equivalent) and run phpMyAdmin. Select your MODX database and open the modx_user_attributes table. Find the default admin user (it should be the first record). Make sure blocked, blockeduntil, blockedafter, and failedlogincount are all set to 0. If not, click on the little pencil at the left to edit that record. Set those fields to 0 in the Value column, and click on the "Go" button at the bottom.

Now open the modx_manager_users table (in MODX Revolution it's just modx_users) and find the default admin user. Make a note of the username. Click on the little pencil to edit that user, enter e10adc3949ba59abbe56e057f20f883e in the password field, and click on the "Go" button at the bottom. This sets your password to 123456.

You should now be able to login using the original username and the password: 123456. Be sure to change your password to something more secure after logging in.

Important note — As of MODX 2.1, you need to use the method described here.

I turned on CAPTCHA and now I can't log in to the Manager because the image doesn't show. What do I do?

Edit the assets/cache/siteCache.idx.php file and change:

$c['use_captcha'] = "1";

to

$c['use_captcha'] = "0";
Important: as soon as you log in, go to Tools | Configuration (System | System Settings in MODX Revolution) and turn Captcha off or you'll be locked out again.

To use Captcha, the server must have GD and Freetype capability in order to show the image.

How did you create this marvelous FAQ?

The FAQ uses some JavaScript code from DynamicDrive.com and is extremely easy to create and maintain in MODX thanks to the EZfaq Snippet, created by (ahem) me. Go here to see the EZfaq tutorial.

 

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book may still be available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting BobsGuides.com

  —  Bob Ray