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.
What's the best way to search for information about MODX?
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?
Is there a Fantastico script for installing MODX?
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?
The installation instructions refer to an "archive" file. What is that?
The installation instructions refer to the "root" directory. What is that?
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?
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 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?
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?
Is there a server for Mac OS X?
How about a linux version of XAMPP?
I have MODX installed: Now what?
Where do my files/documents/pages go?
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?
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?
The "Create/Edit Resource" panel has a lot of fields. Do I need to fill in all of them?
What's the difference between the "Published" and "Show in Menu" checkboxes?
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?
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?
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?
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?
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"?
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?
Templates are discussed in more detail here and here.
What is a chunk?
What is a chunk tag?
MODX Evolution: {{MyChunkName}}
MODX Revolution: [[$MyChunkName]]
Chunks are discussed in more detail here.
What is a snippet?
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 looks like this:
[[SnippetNamee? &property1=`something` &property2=`somethingElse`]]
Snippets are discussed in more detail here and here.
Why isn't my snippet tag working?
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?
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?
Why does MODX keep taking me to my home page?
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?
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?
I get an error message relating to my /tmp directory. What does that mean?
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?
Why don't my changes show up on the site?
I see references to static and dynamic content. What does that mean?
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?
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?
What if a snippet on the page produces information that changes every time the page is visited?
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?
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?
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?
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?
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?
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 Revolution, go to System -> System Settings and check the value of upload_maxsize.
I'm blocked and/or I forgot my password. What now?
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?
$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?
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