Explanation of Directory Structure

The root directory of MODX is split into several subdirectories, each with its own set of responsibilities and tasks. Some of these directories can be renamed and moved, and their locations can be configured during setup.

connectors/¶

Connectors are essentially entry points for AJAX requests in MODX. They don't do any database manipulation on their own; they simply load up the main MODX class, sanitize any request data, and then handle the request by pointing to the appropriate Processor file.

For example, when we create a resource, we request connectors/resource/index.php?action=create. The index.php file will include the base connector file (connectors/index.php) which instantiates the main MODX object, handle any custom Context switching, and sanitize the GET or POST request. The connectors/resource/index.php will then "handle" the request and call the correct Processor file, which we will discuss later.

Notable Files¶

• connectors/index.php- This file is particularly useful in creating your own connectors. Simply include this file in your connectors, and then handle the request using $modx->request->handleRequest();

core/¶

The Core is what makes MODX, MODX. It is the base for all the libraries for Revolution. Most everything you need, with the exception of the manager files and the setup files, are in this directory.

core/cache/¶

The cache directory contains all of the cache files generated by MODX. Lexicons, elements, resources, RSS, and Smarty data are generated on-demand by MODX, meaning that they are only cached after being accessed for the first time.

core/cache/logs/¶

All file logging in MODX is done here. You will find the error.log file here, which contains the date, time, file, and error which was logged by MODX.

To log an entry to this file, you can use the $modx->log() method.

core/cache/mgr/¶

This directory contains cache data for the mgr (Manager) context. Like every context cache, it will cache any context settings that have been overridden from their default System Settings.

core/cache/rss/¶

A cache of every RSS feed in MODX.

core/cache/web/¶

Unlike the cache in MODX Evolution, the MODX Revolution cache is split up into several parts. Every context (ie. web and mgr) has a context.cache.php file. This file is like the config.cache.php file, except that it only caches settings that have been overridden from their default System Setting. Any context can override a system setting.

Additionally, the web context cache will contain separate directories for resources and elements. A resource with ID 12 will be found at cache/web/resources/12.cache.php. This new caching mechanism means that loading times will decrease, and the limit on the number of cacheable resources will disappear.

core/components/¶

When you install a package using the Package Manager, a core/components/ / directory will be created to hold any files necessary for the installed component to run. Typically, any files needed to run in the Manager, such as controllers, model/schema data, processors and class files, should be stored here, as well as files you don't want web-accessible.

core/config/¶

This directory contains the configuration file for MODX Revolution. It sets up database credentials and a number of MODX_ constants for the proper operation of your site.

core/docs/¶

This directory contains the changelog.txt file, the GPL license, and any tutorials that have been created for Revolution.

core/error/¶

This contains default templating for error response messages in Revolution's front-end. You can customize those pages here.

core/export/¶

After running the Export function in MODX Revolution, the exported HTML files for your site will be located here.

core/import/¶

To run the Import function in MODX Revolution, you need to move your HTML files into this directory.

core/lexicon/¶

Lexicons in Revolution are different from language files in Evolution for two main reasons.

First, in Revolution, lexicon files are split up into separate directories, depending on their two-digit IANA code (for example, English lexicons are stored in /core/lexicon/en/). Inside these subdirectories are multiple files, in the format "topic.inc.php". A "topic" is simply a single lexicon file. Splitting lexicons into topics means that only the _required_language strings are loaded, saving memory and loading time.

Second, all lexicons are stored in the MODX database, and later cached on-demand. This makes it possible to manage lexicons directly from the Manager, inside the [Lexicon Management]area.

To load a lexicon, one would use a format such as this:

$modx->lexicon->load( 'lang:namespace:topic' );

# lang- the 2-digit IANA code. This is optional, and defaults to 'en'.

1. namespace- Each lexicon has its own Namespace. The built-in namespace for MODX is "core". Package creators will also be able to create a custom namespace, and Manager users can also create their own namespaces as well.
2. topic- The specific topic/file you want to load.

core/model/¶

This is the model. What's a model, you say? Well, it's the M in MVC (model-view-controller), which is an OO paradigm that states that there should be at least three parts to an application. The Model, which contains the structure of the database and the hooks into it; the View, which is the GUI part of the application that contains no logic - just presentation; and the Controllers, which connect the model to the view.

So, MODX does model sort-of similar. We actually do a MVC/C model, in which we add a Connector access point and Processors to the model. We'll explain those as we come to them. What you need to know is that the model contains all the PHP classes that run Revolution, including the processors that handle specific functions - such as saving snippets, removing chunks, etc.

core/model/modx/¶

"Wait! I thought we were already in a modx dir? Why another modx subdirectory?" Good question. Well, MODX Revolution uses xPDO for its database management. xPDO uses the idea of 'packages' for different connections to different models. So, if I wanted to create my custom tables, I'd create a new xPDO package, and add it in at runtime. This way I could use the maps and classes created without having to modify the MODX core. This is shown in the Creating a 3rd Party Component tutorial.

So, that said, it can be inferred that the core/model/modx directory is referring to the "modx" package. Let's go inside it, and you'll see a ton of classes. These are the classes that are either xPDOObjects - which are PHP classes that represent tables in the DB (ie, modsnippet.class.php is a PHP class that is an object of modx_site_snippets), or they are functional classes, such as modcachemanager.class.php.

The subdirectories in this folder - not including mysql or processors - are subcategories of classes, that are loaded like: $modx->loadClass('transport.modPackageBuilder'); with the "." being the separation of directories.

core/model/modx/mysql/¶

This directory contains the class and map files for each xPDO object. Maps are simply PHP arrays containing the structure of the database table they reference.

Other database platforms such as pgsql, mssql, and others would also appear here.

core/model/modx/processors/¶

This directory contains the individual processor files used in database manipulation. They are never accessed directly, and instead are accessed through connectors. This allows you to lock them down to prevent unauthorized access.

core/model/schema/¶

The schema is the XML representation of the MODX database. This is used in building new maps and classes, but is never actually read or parsed when MODX is running. For the most part, you can ignore this directory, as it is mainly used for development work. The tutorials on creating 3rd party components teach more about schemas.

core/model/smarty/¶

This contains the Smarty libraries. It's simply an extraction of the Smarty files you can get from http://smarty.php.net. Nothing in this folder is customized for MODX - that happens elsewhere.

Smarty is an intelligent, object-oriented templating engine that uses dynamic, modifiable placeholders. Most pages seen in the Manager and during Setup are Smarty template (.tpl) files that MODX interacts with.

When you edit a resource (often a document) in the Manager, for example, you're looking at a page generated by the controller at manager/controllers/resource/staticresource/update.php. After setting the characteristics of the resource in the $resource array, this code renders the page:

$modx->smarty->assign('resource',$resource); return $modx->smarty->fetch('resource/staticresource/update.tpl');

The Smarty placeholders in update.tpl are filled in with the data held in the $resource array.

core/packages/¶

Here you will find any transport packages you've downloaded via the Package Management section of Revolution, such as TinyMCE, Ditto, etc. The core package is also found here as well. This allows for easy installation and removal, as well as remote updating of installed packages.

When you build a package (for example, after checking out from SVN), the transport package will be stored here.

core/xpdo/¶

MODX Revolution was designed to use OpenExpedio (xPDO), an extension to PDO. It provides a uniform interface for manipulating databases, and makes it possible for MODX to support various database platforms besides MySQL.

This directory contains all of the class files needed by xPDO to do everything from query caching, to building transport packages and outputting data as a convenient JSON object.

These classes are used by MODX internally, and developers should never need to deal with them directly.

Notable Files¶

• core/cache/config.cache.php - This is the cache file for all of the System Settings in MODX. Their database equivalents are found in the _system_settings table, and their xPDO equivalents are modSystemSetting objects.
  • Tip - If you ever get locked out by the CAPTCHA component, you can edit this file and set use_captcha to '0' to disable CAPTCHA. Then you can log in and disable CAPTCHA in System Settings.
• core/cache/sitePublishing.idx.php - In MODX Evolution, this file contained the cache data for all documents, chunks, and snippets. In Revolution, this is no longer the case, and this file now keeps track of cache refresh intervals.
• core/cache/mgr/actions.cache.php - a map of all modAction objects.

manager/¶

The Manager is the MODX backend or administration area for creating resources, managing users, and performing overall site maintenance tasks.

manager/assets/¶

This directory contains the ExtJS libraries, as well as the custom ModExt implementation. ModExt extends the original ExtJS library, to make development more convenient for users.

manager/controllers/¶

Controllers are the PHP files tied to modActions. They simply fetch data and return or output it to the browser for rendering and display. Whenever you load a page in the Manager, you are in effect telling MODX to load a particular Controller, which simply loads a Smarty template and outputs any necessary JavaScript to the browser.

manager/templates/¶

This directory contains the template files for each manager page. They do not contain PHP code, but rather are used to organize HTML. If you are looking for the Smarty .tpl file for a particular manager page, check in the manager/templates/default/ directory.

Notable Files¶

• manager/assets/ext2/ext-all.js - This is the main Ext library file, which must be included on all Manager pages (or any page using Ext). It's compressed to save space, decrease download time, and speed up page loads. However, if you're doing a lot of JavaScript work, you're bound to run into some cryptic errors because of the compression. The best way to deal with this is to simply rename this file, and then rename the ext-all.js file to ext-all-debug.js to use the uncompressed version during development. Just be sure to switch them back afterwards!

setup/¶

This directory contains the necessary files needed to run Setup and perform a Fresh Installation or Update.

_build/¶

This directory is only present in version of MODX Revolution downloaded from the subversion server (as well as the "SDK" distribution). It contains the packaged MODX core data files necessary to install MODX to a database.

Notable Files¶

• _build/transport.core.php - This file must be executed after downloading MODX Revolution, and prior to running Setup. After completion, you should notice a "core" directory inside your core/packages/ directory, which will contain all of the necessary [Vehicles]for installing MODX Revolution.

assets/¶

This directory is not present in MODX Revolution by default, but it is common to place images, CSS, JavaScript, and other media in here.

assets/components/¶

When you install a package using the Package Manager, an assets/components/ directory will be created to hold any necessary component files, such as JavaScript or images.

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 

Budget

$306 per month—let's make that $500!

Learn more