The MODX Constants

The MODX Constants

In PHP Code, there are a number of MODX constants that come in handy for referring to files and URLs 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 you are operating outside of MODX. Remember that this first set will only work in PHP code, we'll see how to use them in HTML code in a bit. 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 http:// prefix)
MODX_SITE_URL -- MODX root (with the http:// prefix)
MODX_ASSETS_URL -- URL of the assets directory
MODX_MANAGER_URL -- URL of the manager directory
MODX_CONNECTORS_URL -- URL of the connectors directory

Note that these do not exist: MODX_CORE_URL, MODX_PROCESSORS_URL.

Your site should deny web access to the core directory. 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, but the MODX processors are class files, so there's no need to access them by URL.

Remember that all the MODX constants end with a slash. Whatever you put after them should never begin with a slash!

Most MODX extras install files in both the core/ and assets/ directories. The files in the assets/ directory (under assets/components/extraName/) are the typically ones that must be accessed by URL, such as images, JS, and CSS files.

Shortcuts in HTML code

All 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]]

Notice that because these are System Setting tags, they begin with two plus signs. It's a common mistake to use placeholder tags, which begin with a single plus sign.

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 referring to a background image, for example, that reference will be relative to the CSS file itself, not the MODX root directory (the one that contains the 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.

Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.