Sometimes, when you load up a page, say for a snippet you’re working on, everything on the page runs down the left margin and is all in the same font and style. Usually, that means that your CSS is not being loaded by the browser. In this article, we’ll look at how to troubleshoot that situation.
The first thing to do is a “View Source” on the page (Ctrl-U in many browsers). This will show you the raw HTML code of the page. First, check to make sure that there is a
<head> section at the top of the page. If you forgot to put a
<head> section in your template, the CSS won’t be recognized by the browser and the MODX code usually used to inject CSS won’t function. Sometimes this happens when the page template accidentally gets switched to a blank template.
Assuming that the
<head> section at the top of the page is there, you should see a line something like this:
<link rel="stylesheet" href="/assets/components/yourComponent/css/mySnippet.css" type="text/css"/>
If there is no such line, then you need to look where your CSS is supposed to be injected (snippet code, template, chunk, etc.). Whatever is supposed to be putting the line there isn’t doing its job.
If the line is there, click on it. In most browsers, this will load the CSS file as if it were a text file and show it to you. If nothing happens when you click on it, the URL of the file isn’t correct.
While you’re looking at the source of the page, check to make sure that the
base href tag is there and is correct. If it’s not, your CSS probably won’t load correctly. Typically the
base href tag results from a tag like this in the
<head> section of the template:
<base href="[[++site_url]]" />
Make sure the
base href tag is there, is correct, and is a “short” tag. If your site has more than one front-end context, the
base href tag should look like this, with the tag called uncached:
Some Common Problems
There are several reasons why the link to the CSS file won’t work. One is a permission problem with the CSS file itself. A second possibility is that the file is in a location that can’t be reached by URL. Generally, CSS files are placed under the
assets/ directory, where they are accessible by URL. If you have placed your CSS file under the
core/ directory and either that directory is above the web root or is protected from direct HTTP access, that’s why your CSS isn’t loading.
In my experience, the most common reason why CSS won’t load is confusing a path with a URL. If the link you see in the source is a physical path to the file, it won’t work. It has to be a URL. It doesn’t have to be a full URL, but sometimes making it one will correct a faulty URL.
If you are registering the CSS in code, this is typically the method you would use (note the use of the MODX_ASSETS_URL constant):
$cssPath = MODX_ASSETS_URL . ‘components/mycomponent/css/cssfile.css’;
Less Common Problems
There’s a description of an uncommon cause of CSS not loading in this Forum post.
If you are placing the CSS in a resource or in a chunk placed in a resource, or using a static resource for the CSS, make sure the resource has an empty template. Otherwise, the browser will be trying to interpret the template’s HTML code as CSS and may get very confused.
If the CSS in injected by a nested process, e.g., the template contains a chunk tag, the chunk contains a snippet tag, and the snippet injects the CSS, the parsing order may be a factor. You can experiment with making the various tags cached or uncached, but it’s usually better to simply reduce the level of nesting. We’ll discuss this concept in more detail in a later article.