How MODx Works
MODx works in two parts. One part parses documents to generate dynamic web pages, while the other part provides the Manager interface and functions.
To begin with, we'll look at how MODx generates a dynamic web page.
How the MODx Parser Works
When a page request loads the front-end index.php file, the server includes either the ID or the alias of the document being requested, depending on your site's configuration. The index.php file initializes the modx object and starts the parser.
The parser takes a number of steps to determine exactly what response goes back to the server:
- Determine the site's availablitly status from the site configuration. If the site is "offline", display the "unavailable" page specified by the configuration, or generate a default simple "unavailable" page with a message taken from the manager's language file.
- Has it been passed a document ID (id=42) or an alias (q=page.html)? If it's the alias, determine the document's ID.
- If the document is cachable, check the cache and get the cached document. Make sure the viewer has permissions to view the document, check for uncached snippet calls and process them, then return the document and exit.
- If the document does not exist, is tagged for deletion, or is not published, send the site's error page and exit.
- If the document is private, check the viewer's SESSION array to make sure he has permissions to view the document. If he doesn't, send the site's "forbidden" page and exit.
- If the document is a weblink, generate the proper URL from its content, redirect the viewer to the URL and exit.
- Get the document's template (or use the document's content if it uses a "blank" template) and process the MODx tags in the template. (how templates work)
When the final output is ready, MODx send it to the server with a rather anti-climactic echo statement:
echo $this->documentOutput;
How the MODx Manager Works
When you request the manager/index.php page, the first thing it does is check to see if you are logged in, and displays the login form if you are not.
Once you are logged in, the manager/index.php page has a long list of possible actions to take. The requested actions are passed in the URL query string. The default action, which will be what happens when you first log in, is to display the Manager Home or Welcome page.
From that point, each menu item you select will request the manager/index.php page with its ID in the query string. The switch structure in the index.php file will include the appropriate .php file to display the content for the action you've selected in the right workspace frame.
When you save your work, a corresponding processor .php file is used to process the forms and return you to the appropriate Manager page.
Manager Templates
The Manager template is specified in the Configuration. The templates and supporting css and image files are stored in manager/media/style.
MODx comes with three different templates, and there are several more available at the MODx Resources site. Some of these were designed for earlier versions of MODx, so make sure to check their version support. If you try one of these templates and it trashes your Manager, you'll need to go to the database and change the setting in the system_settings table for the manager_theme field.
The default is MODxLight.
Manager Frames
The Manager page has three frames.
- Across the top is the main menu.
- On the left is the Document Tree. This displays a tree-like structure to illustrate the parent/child relationship of the documents. From the Tree you can select the document you wish to work with, or create a new document in the part of the Tree where you want it to be.
- On the right is the main Manager workspace. This will vary depending on what action you select from the main menu.
Most of the resources are stored in the database. What is displayed in the editing fields for the resources is taken from the database. Most of the resources also have a tab with fields for configuring the resource. Some snippets, modules and plugins will have a minimum of initialization code in the database, while the rest of the code is in libraries or classes in the filesystem and is included by the viewable code. All of the resources can be stored in files if this is preferred; how to do this will be explained in the section covering snippets.
The Manager also loads and starts up the parser, to enable it to use all of the library functions for accessing the database, user log-in status and the site configuration.
When you first install MODx, you are usually presented with the Configuration workspace. This can also be opened from the Tools -> Configuration menu item. There are several tabs for different sections of the configuration. Go through the Configuration and look at the various options. Most of them have a basic description of their purpose. To begin with, just set the Site Name to the name of the site. In the illustration below, I've used my domain name. That's not at all a requirement; I just couldn't think of a clever name for my site.
The settings from the configuration, which are stored in the system_settings table of the database, plus a few from the config.inc.php file that was created when you installed MODx, can be accessed in HTML by the [(fieldname)] tags, such as [(site_name)] . In PHP code, they can be accessed with
$modx->config['fieldname']
As with most of the actions in the workspace, you can save your changes by clicking on the 
buttons at the top and bottom of the workspace.
The MODx Manager Main Menu
Take a few minutes and go through the main menu and see what the different menu items offer.
Site
The Site menu has six items.
- Home will display the Manager's main home or Welcome page in the workspace. This will show any errors in the MODx configuration. A common error is that PHP is configured with register_globals ON. The site will still work, but this can be a serious security problem. The first tab on the Manager's home page offers a few quick links to other Manager functions, and notifies you if you have any private messages in the Manager messaging system. Newer versions of MODx also have tabs for links to the latest news and security notices from MODx.
- Preview will open your site in a new browser page or tab.
- Clear Cache item will clear the cache files for all documents. This is often necessary when developing a site. Normally, when a document is edited and saved, the cache will be cleared for that document, but if you are working with templates or chunks, you'll need to clear the cache to see your changes.
- Search allows you to search for a document.
- New Document opens a document editing form in the right frame for creating a new document.
- New Weblink will open a weblink editing form for creating a new weblink.
Resources
The Resources menu offers three items.
- Manage Resources has a set of tabs for managing Templates, Template Variables, Chunks, Snippets and Plugins. These will all be covered thoroughly later on.
- Manage Files opens the Manager's File Manager, giving you access to the folders and files in the site's assets folder. Depending on your site's configuration, you may or may not be able to manipulate the files in all of the folders. Folders that have permissions to allow the php scripts to write can upload files, and often edit them as well.
- Manage META tags and keywords allows you to enter all of the META tags and keywords you will want to use for the entire site. Later, for each document, you can select which of these META tags and keywords you want to use for that document. This system is not very friendly, and is seldom used. An explanation of how to use Template Variables as a much better system of managing META tags and keywords will be given in the section on Template Variables.
Modules
The Modules menu will have at least one item, Manage Modules. This allows you to create new modules or edit and enable/disable existing modules. Modules are the way to add extra functionality to the Manager without having to modify the core manager scripts. The Modules items will reflect all of the modules that are installed. By default MODx comes with the DocManager and QuickEdit modules pre-installed.
Security
The Security menu offers the various items for managing the users for your site, both front-end web users and Manager users. The MODx security system will be covered in depth later.
Tools
The Tools menu provides a number of items for managing the site:
- Backup allows you to back up your site's database. It also has a feature to optimize the tables, and empty the event log and the manager actions log.
- Remove Locks will clear the locks MODx puts on resources and documents that are being edited by another user.
- Import HTML imports static HTML pages into MODx documents.
- Export Static HTML exports MODx document to HTML pages. These will be static pages; dynamic and interactive snippets won't be available.
- Configuration is for setting the main site's configuration values.
Reports
The Reports menu offers items to provide information about your site.
- Schedule displays when documents are to be published or unpublished.
- System Events is an error log, displaying any errors produced by generating pages or running modules or plugins.
- Manager Actions is a log of all the actions of manager users while they are logged in. This allows you to see who edited what, who installed what snippets, or anything else any of the manager users did.
- System Information gives several pieces of information about your site, including what tables are in the database. There is also a link to a phpinfo() function, which is always interesting to look at. This is also very useful if you are having issues with accessing files or images and need to check the paths on your server. At the very bottom of the phpinfo() output are all of the $_SERVER array values, including the path from the root of your server to the manager. These values are necessary in the Configuration, both in the Interface and Features tab for the Resource Browser to be able to access your image files, and the File Manager tab to allow the File Manager to access your assets folder and its files.
Both the System Events and the Manager Actions are stored in the database, and occasionally should be checked and cleared if they are getting too big.