Bob's Blog

New users of MODX (and sometimes experienced users) can have trouble when adding references to images, and CSS, JS, or other files. In this article, we'll look at some tips that will help you use references that will make sure the files are found. Some of the information below is borrowed from an excellent MODX Forum post by Susan Sottwell.

MODX Versus Direct Access

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 ask the server for that physical file. When the server 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]]"/>

When MODX generates the URL for a page, it will be prefixed it with the site URL (e.g., https://yoursite.com/) becasue of the base href tag. 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.

Some Useful Shortcuts

In PHP Code, there are a number of MODX constants that come in handy for referring to files of various kinds. These are the most useful ones:

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';
[/code/

<p>Incorrect:</p>
<pre class="brush: php; toolbar: false;"><fixedpre>
$path = MODX_ASSETS_PATH . '/components/mycomponent/somefile.php';

The second example is incorrect because the MODX_ASSETS_PATH already has a slash at the end. The extra slash at the beginning of the rest of the path will cause a double-slash in the middle of the path.

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 and 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.

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 location of 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 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.

 

---

Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at Hosting.com (formerly A2 Hosting). (More information in the box below.)