Bob's Blog

When I was new to MODX, I was often confused about where and how MODX got configuration information about the site. Clearly MODX knew where to find things, but I had a very vague notion of how it was done. In this article, we'll look at the process and at the contents of the config files. We'll also take a look at the MODX constants and how to refer to file locations from various places in MODX.

The Basics

All of the configuration information available for your site is contained in four files (five, if you count the one in the setup directory). One is the master configuration file config.inc.php. All the other files do is tell MODX how to find the master config file. That master config file can be renamed, but it will always be found in the config/ directory just below the MODX core directory (which can also be renamed).

The other files are all named config.core.php. Their only job is to tell MODX where to find the master config file. The config.core.php files can't be renamed. They are located in the MODX root, connectors, manager, and setup/includes directories. Once MODX is installed the config.core.php files should all be the same and should contain correct information about where the core is and what the config file is named.

Here's an example of the config.core.php file contents from the MODX root directory of a localhost install:

<?php
define('MODX_CORE_PATH', 'C:/xampp/htdocs/mysite/core/');
define('MODX_CONFIG_KEY', 'config');
?>

This file contains only two pieces of information. First, it has the path to the core directory: C:/xampp/htdocs/mysite/core/. If the core were renamed, the core part of it would be different. If the location were changed, the path would be different. The second piece of information here (in the second line) tells MODX the name of the config file. In this case, it's the default: config.inc.php. If the second line looked like this:

define('MODX_CONFIG_KEY', 'myconfig');

MODX would know to look for a config file named myconfig.inc.php in the directory specified in the first line.

The Process

When MODX is launched, it looks at the config.core.php file in the MODX root directory. This file is the one that's used most often. The other config.core.php files contain the same information and are only there for convenience and the option to use simpler relative URLs in the other directories. Onece the root config.core.php file has been read, MODX knows exactly where to find the master config file. It reads that master config file, and has no more use for the config.core.php file, since the master config file contains everything it needs to operate.

Setup

When you run setup, one of its jobs is to rewrite the various config.core.php files and the master config file (by default: config.inc.php). It uses the information provided in the forms of the setup process for this. It doesn't always get everything right, especially when you move a site to a new server. When you move a site, always run setup before trying to log in. It's also a good idea to delete all files in the core/cache directory. If the site still has problems, take a look at the config.core.php file in the MODX root to make sure that the location of the core and the name of the master config file are correct. If they are, look in the master config file itself and check all the paths and URLs. The MODX_CONNECTORS_PATH and MODX_CONNECTORS_URL are most likely to be incorrect.

<?php
if (!defined('MODX_CORE_PATH')) define('MODX_CORE_PATH', MODX_INSTALL_PATH . 'core/');
if (!defined('MODX_CONFIG_KEY')) define('MODX_CONFIG_KEY', 'config');
define ('MODX_SETUP_KEY', '@traditional@');

In the current traditional distribution of MODX, setup assumes that if the core path hasn't been defined, it will be called "core" and will be located in the MODX root. If this isn't correct, and the core can't be found in the that location, setup will ask you where the core is.

If you're using Friendly URLs (FURLs) in MODX, the rewrite rules in .htaccess will route requests through the index.php file in the MODX root directory. This only happens, however, if the file referenced in the URL is not found. By default, MODX stores the content of its web pages in the Database. When you enter a URL like mysite.com/home.html, your browser will look for that physical file. When it doesn't find it, the rewrite rules will launch index.php and MODX will build the page on the fly based on the information in the URL.

If, on the other hand, you actually have a file called home.html in the MODX root directory, it will be found. Your browser will display it, and MODX will never be involved in any way. I've helped new MODX users who were converting a site to MODX and tearing their hair out because none of the stuff they did in the MODX Manager had any effect. This happened because they still had an index.html file in the MODX root. MODX's index.php file never came into play, and MODX was never launched.

Because MODX routes everything through the index.php file in the MODX root directory, any paths or URLs in your HTML code need to be relative to the MODX root. This includes img, css, and js references in the code — more on this in a bit.

URLs versus Paths

I've been working with MODX for years, but this issue still bites me occasionally. If you are using include, include_once, require, or require_once to include a file in your PHP code, you want a file path, *not* a URL. The path needs to give the physical location of the file on the server. For images, CSS, and JS files, on the other hand, you want a URL, not a file path.

It's important to remember that if the reference is a URL, the location must be available by URL. That means it has to be in or under the web root of the site. If you move the core outside of the MODX web root (highly recommended), you can't put anything in or under the core directory that needs to be available by URL. Images, CSS, or JS files there won't be found by the browser.

The Base Href Tag

As you probably know, links to pages on your site should always be in the form of link tags:

<a href="[[~12]]">Some Page</a>

In the example above, 12 is the ID of the resource you want to link to. The ID is shown in parentheses next to the pagetitle in the Resource tree at the left of the Manager. By using link tags, you can move your site to a new server, reorganize, or rename the pages and the links will still work. For this to work correctly, though, you need a base href tag like this in the head section of all templates:

<base href="[[++site_url]]"/>

If you have more than one front-end context, the tag should be called uncached (note the added exclamation point):

<base href="[[!++site_url]]"/>

Be sure to use a short tag for the base href statement. Using a closing tag will often cause problems.

When MODX generates the URL for a page, it will prefix it with the site URL (e.g., https://yoursite.com/). Although the tag above is a Setting tag, there's typically no System Setting with that key. MODX generates the setting based on the URL the user used to access the site. If you have multiple front-end contexts, though, you'll want to create a site_url Context Setting for each of them. In that case, MODX will use the value for the current context rather than generating it from the URL.

The MODX Constants

In PHP Code, there are a number of MODX constants that come in handy for referring to files of various kinds. They are not only convenient, they also assure that the path will still be correct if the site is moved. You should never hard-code the actual path to a file, unless your are operating without MODX. Remember that these only work in PHP code. Here are the most useful constants:

MODX_BASE_PATH -- path to the MODX root
MODX_CORE_PATH -- path the MODX core directory
MODX_ASSETS_PATH -- path to the MODX assets directory
MODX_MANAGER_PATH -- path to the MODX manager directory
MODX_CONNECTORS_PATH -- path to the connectors directory
MODX_PROCESSORS_PATH -- path to the processors directory

Remember that these are paths, not URLs, and that they all end in a slash:

Correct:

$path = MODX_ASSETS_PATH . 'components/mycomponent/somefile.php';

Incorrect:

$path = MODX_ASSETS_PATH . '/components/mycomponent/somefile.php';

The second example will give you a double slash in the URL because the constant's value already ends with one.

There are equivalent constants for URLS. They also end in a slash:

MODX_BASE_URL -- MODX root (without the https:// prefix)
MODX_SITE_URL -- MODX root (with the https:// prefix)
MODX_ASSETS_URL -- URL of assets directory
MODX_MANAGER_URL -- URL of manager directory
MODX_CONNECTORS_URL -- URL of connectors directory

Note that these do not exist: MODX_CORE_URL, MODX_PROCESSORS_URL. MODX recommends moving the core directory above the web root. This means that any files in or under the core can't be accessed by URL. The MODX processors directory is typically under the core directory so the same applies to its files. That's why many MODX extras install files in both the core and assets directories. The files in the assets directory are the ones that must be accessed by URL, such as images, JS, and CSS files.

Shortcuts in HTML code

All of the constants above can also be referenced in HTML code using a setting tag, but they are used less often because the base href tag prefixes everything with the site URL, so paths and URLs are usually relative to that. Here are some examples of typical Setting tags. Notice that these are in lowercase and don't include the modx_ prefix:

[[++core_path]]
[[++manager_path]]
[[++assets_url]]
[[++manager_url]]

Files in Files

We said above that references in MODX templates and page content are relative to the MODX site root. This is *not* the case, though, for references that are in physical files. If your CSS contains a url reference to a background image, for example, that reference will be relative to the CSS file itself, not the MODX index.php file.

As we saw above, the reference to the CSS file might look like this:

<link rel="stylesheet" type="text/css" href="assets/css/mycss.css"/>

Inside the CSS file, though, a reference to a background image must be relative to the CSS file itself. If your background image is in the same directory as the CSS file containing the reference to it, you can refer to it by the file name alone:

background-image: url(rss.png)

If the image is above the CSS file in the directory structure, you can use the .. operator, which refers to the directory above the current one. For example, if your directory structure looks like this:

    assets
        images
            rss.png
        css
           mycss.css

the reference to the rss.png file in the mycss.css file would look like this:

background-image: url(../../images/rss.png);

The ../.. part translates to the assets directory (up two levels). From there, the path /images/rss.png takes you down to the correct location. It doesn't matter how these directories are placed relative to the MODX root, we're simply telling the browser to go up two directories, then down to the rss.pngfile in the images folder. In fact, MODX is not involved in this process at all. The browser finds the file relative to the CSS file it is processing. The same thing happens with URLs inside of JavaScript files — they need to be relative to the location of the JS file.

Similarly, references in a file that use include, include_once, require, or require_once are always relative to the file containing the reference. If they are in the same directory, the filename alone is enough. If they are somewhere else, you should use one of the MODX path constants or the ../ trick described above so they will remain correct if the site is moved.