MODx Newbie FAQ
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.
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.
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).
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.
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. 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.
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.
You can download the latest stable release of XAMPP for Windows here.
You can download the latest stable release of XAMPP for Windows here.
Is there a server for Mac OS X?
How about a linux version of XAMPP?
Yes. Look here for the linux version (formerly called LAMPP).
I have MODx installed: Now what?
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.
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 http://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.
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.
The "create new document" form 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. The Show in Menu checkbox just sets a flag that the Wayfinder snippet can use to decide whether or not to show the document in the menu.
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.
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).
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.
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.
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.
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.
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 call. 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 call?
A chunk call 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 call looks like this:
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 "call" on the page.
When MODx sees the snippet call, it finds the snippet, has it generate the output, and puts that output on the page in place of the snippet call.
Go here to learn more about snippets.
When MODx sees the snippet call, it finds the snippet, has it generate the output, and puts that output on the page in place of the snippet call.
Go here to learn more about snippets.
What is a "snippet call"?
A snippet call is just a tag (or marker) in a MODx document that tells MODx that you want the output of the snippet there.
A snippet call looks like this:
A snippet call looks like this:
Why isn't my snippet call working?
There are four mistakes that account for 99% of the failed snippet calls:
1. Snippet names and parameters are case-sensitive. Make sure you spelled your snippet name correctly. "startID" will not work if "startId" is expected.
2. Snippet parameters must be enclosed in backticks, not single quotes. The backtick character is usually on the ~ key.
3. Each parameter in a snippet call 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 call.
1. Snippet names and parameters are case-sensitive. Make sure you spelled your snippet name correctly. "startID" will not work if "startId" is expected.
2. Snippet parameters must be enclosed in backticks, not single quotes. The backtick character is usually on the ~ key.
3. Each parameter in a snippet call 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 call.
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).
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).
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.
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 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 call (the exclamation marks are the only difference):
To tell MODx to call the snippet uncached, use the following form for the snippet call (the exclamation marks are the only difference):
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.
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 call), written a long time ago. As the site grows, they automatically include the new documents.
The two menus on the right side of this page are each generated by a single line of code (a Wayfinder snippet call), 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.
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.
Once it's in the MODx database, you can access the data with the MODx DBAPI, usually in a snippet.
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.
Thank you for visiting BobsGuides.com
— Bob Ray
