Using MODX Settings

How to use modx settings in various locations.

By Bob Ray  |  February 3, 2026  |  6 min read
Community MODX CMS Tutorials
Using MODX Settings

In my previous two articles, we digressed a little to discuss internationalization of MODX settings and creating multiple translations. In this one, we'll return to the topic of MODX settings, and see how to use them in various locations.

The information in this article applies to all four kinds of settings in MODX:

  • System Settings
  • Context Settings
  • User Group Settings
  • User Settings

HTML

HTML code is probably the most common place you'll see or use MODX settings. In HTML, they will always be in one of two forms:

[[++setting_key]]
[[!++setting_key]]

The first version above is the cached call. If MODX can find the value of the setting in the MODX cache, it will use it. This is fine if the value of the setting rarely changes, which is the case for most settings. Occasionally, though, you may have a setting that changes often. A good example is the tag in the base base href tag that should appear in all MODX templates in this form:

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

The contents of the setting tag is replaced by the actual site URL, which will be used as a prefix for images, CSS files, and JavaScript files.

Since the actual site URL could change if the site is moved or restructured, it's important to call the tag uncached (with the exclamation point) so that the result is always fresh. Otherwise, an old value coming from the cache would keep the required files from being found. That could result in missing images, un-styled pages, or pages that don't work because their JavaScript is missing.

Using tags like the ones above will work with any MODX setting. If there is more than one setting with the same key, the result will depend on the settings hierarchy I discussed in a previous article in this series. Briefly, Context Settings will override System Settings. UserGroup Settings will override Context Settings. And User Settings will override everything else.

Remember that a setting tag always has two + signs. If you use one, MODX will look for a placeholder rather than a setting.

PHP Code

In PHP code, you can access any setting with the $modx->getOption() method like this:

$settingValue = $modx->getOption('setting_key');

As with the tags we saw above, the value is governed by the settings hierarchy when there are multiple settings with the same key. You can specify a default value to use if the setting is not found, but it's seldom necessary since it would be very unusual for the setting not to be found. If you need to make sure, though, you can do it like this:

$settingValue = $modx->getOption('setting_key', null, 'default value');

Often the setting value from the line of code above is used to set a placeholder. In that case, you'd put a placeholder on the page, template, or chunk:

[[+some_placeholder]]

Then the PHP code would look like this:

$settingValue = $modx->getOption('setting_key', null, 'default value');
$modx->setPlaceholder('some_placeholder', $settingValue);

It doesn't happen very often, but if the PHP code is in a snippet (as it usually is), you might want to use the setting as a backup and have a value sent as a property in the snippet tag override the setting. In that case, you'd do this:

$settingValue = $modx->getOption('setting_key', $scriptProperties, 'default_value');

This is basically an extension of the setting hierarchy, since snippet properties will override all other settings. Note that if the snippet tag doesn't contain the property, but there is a setting with the same name, MODX will use the setting value. The null argument in the earlier example tells MODX not to look in the $scriptProperties array. The default value argument is optional, as is a final fourth argument. The fourth argument must be either true or false. If true, MODX will use the default value if the setting exists, or is in the $scriptProperties array, but is empty. If the argument is false, it will return the empty value.

For completeness here, I should mention that properties with the same name as a setting key that are in a property set will override all types of settings. And settings sent as properties in a snippet tag will override properties with the same name in a property set attached to the snippet. This is seldom a problem, but it could happen.

CSS

Normally, you can't put a setting tag in CSS because the browser is in charge of getting the CSS code, and the browser doesn't understand MODX tags. There is a trick to get around that limitation, though. If you put the CSS code containing the setting tag in a MODX chunk, then pull in the chunk in a snippet or plugin, MODX will parse the tag when it gets the chunk's content. That looks like this:

$css = $modx->getChunk('chunkName');
$modx->regClientCSS($css);

The first line above gets the parsed chunk. The second line injects the CSS into the head section of the page's HTML code.

JavaScript

Like CSS, the browser gets JS code and won't parse any MODX tags, but we can use the same trick we used for CSS above, with a small change in the PHP code (assuming that the JS code containing the setting tag is in a chunk):

$jsCode = $modx->getChunk('chunkName');
$modx->regClientStartupScript($jsCode);

Tags inside of Tags

It's entirely possible to MODX tags inside of other tags, so you could do something like this to send the value of a system setting to a snippet:

[[SnippetName? &site_start=`[[++site_start]]` ]]

It's usually best to avoid doing this, though, for a couple of reasons.

First, the setting is readily available in the snippet with $modx->getOption(), and with better control over where the setting comes from and what default value should be used.

Second, nested tags (tags inside of tags) often won't do what you think they will since some inner tag values may not be available at the time the outer snippet is parsed. This is especially true if the outer tag is called cached and the inner one is called uncached. Calling a tag uncached delays its processing, so it the outer tag will receive the uncached inner tag instead of its value and usually won't know what to do with it.

Cheating the Settings Hierarchy

This is really a rare case, but what if you have several types of settings with the same key and want a specific one that's not the one you'd get with $modx->getOption()? Suppose you have a setting (lets call it setting_one) and it's both a Context Setting and a User Setting. In a snippet, you want the Context Setting rather than the user setting. If you called $modx->getOption('setting_one'), you'd get the User Setting for the current user, but you don't want that. You want the Context Setting. You can get it by asking for the setting object directly and getting its value, like this:

$settingObject = $modx->getObject('modContextSetting', array('key' => 'setting_one'));
$value = $settingObject->get('value');

The first line above gets the 'modContextSetting' object itself. The second line gets its value.

Coming Up

In this article we've looked at how to access settings in different locations. In my next article we'll see some examples of practical uses for the various kinds of MODX settings.

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.