How MODx Works
MODx works in two parts. One part parses resources and processes elements 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 resource 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 resource ID (id=42) or an alias (q=page.html)? If it's the alias, determine the resource's ID.
- If the resource is cachable, check the cache and get the cached resource. Make sure the viewer has permissions to view the page, check for uncached snippet calls and process them, then return the resource and exit.
- If the resource does not exist, is tagged for deletion, or is not published, send the site's error page and exit.
- If the resource is private, check the viewer's SESSION array to make sure he has permissions to view the resource. If he doesn't, send the site's "forbidden" page and exit.
- If the resource is a weblink, generate the proper URL from its content, redirect the viewer to the URL and exit.
- Get the resource's template (or use the resource'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 sends 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 1.0 Evolution has some of the manager pages that are most frequently customized (login.html, manager.lockout.html and welcome.html) in assets/templates/manager.
There are several manager templates 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 for 0.9.3 is MODxLight; for 1.0 Evolution it is MODxCarbon.
Manager Frames
The Manager page has three frames. The code for these can be found in the manager/frames folder. The 1.php file contains the structure for the entire page.
- Across the top is the main menu, and the frame name is "mainMenu". Its structure is contained in the menu.php file.
- On the left is the Resource Tree. Its frame name is "tree", and its structure is contained in the tree.php file. More of its dynamic structure is controlled in the nodes.php file. This frame displays a tree-like structure to illustrate the parent/child relationship of the resources. This is a virtual tree; in actuality the resources are stored flat in the site_content table of the database, and the tree is constructed from the value of each resource's parent field in that table. A few other fields, such as the "isparent" and "menuindex" fields, control the placement and icons used in building the tree view. From the Tree you can select the resource you wish to work with, or create a new resource in the part of the Tree where you want it to be.
- On the right is the main Manager workspace. Its frame name is "main". Its structure is controlled by the various .php files in the manager/actions folder. This will vary depending on what action you select from the main menu.
Most of the elements are stored in the database. What is displayed in the editing fields for the element is taken from the database. Most of the elements also have a tab with fields for configuring the element. Some snippets, modules and plugins will have a minimum of initialization code in the database, while the rest of the code is in library or class .php files in the filesystem, usually in the assets/snippets, assets/modules and assets/plugins folders, and is included by the viewable code. All of the elements 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 
button floating at the top 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 Resource opens a resource editing form in the right frame for creating a new resource.
- New Weblink will open a weblink editing form for creating a new weblink.
Elements
The Elements menu offers two items.
- Manage Elements has a set of tabs for managing Templates, Template Variables, Chunks, Snippets and Plugins. These are all covered in depth in later chapters.
- 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.
- Previous versions of MODx also had a third menu item to Manage META tags and Keywords which allowed you to enter all of the META tags and keywords you would want to use for the entire site. Later, for each document, you could select which of these META tags and keywords you want to use for that document. This system was not very friendly, and was seldom used. An explanation of how to use Template Variables as a much better system of managing META tags and keywords is given in the chapter 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 module 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 elements and resources that are being edited by another user.
- Import HTML imports static HTML pages into MODx documents.
- Export Static HTML exports MODx resources 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 resources 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 and your site's URL and path. There is also a link to a phpinfo() function, which is always interesting to look at.
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.
Comment On This Article
Do you find something unclear? Did I miss something or get something wrong? What do you like or not like about this chapter? Please do not ask for help here; use the forums if you need help.