System Settings

Last updated Mar 19th, 2021 | Page history | Improve this page | Report an issue

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

Budget

$301 per month—let's make that $500!

Learn more

MODX comes with a flexible amount of system settings. They are found in System -> System Settings, and can easily be edited and changed. All system settings are available in your templates by using the [[++placeholder]] notation. See Template Tags for more information.

Overriding Settings (Inheritance)¶

While this document mostly talks about System Settings, MODX comes with a very powerful inheritance system that allows you to override settings at the context, usergroup, or user setting.

Basically, when a setting is requested in the session of a specific user, the settings are checked in the following order:

User Setting
Usergroup Setting
Context Setting (Note that in the manager, the context is usually mgr)
System setting

Creating new System Settings (via the GUI)¶

To create a new system setting, click the "Create New Settings" link under System -> System Settings.

Parameters¶

Key: This is ultimately the unique name of your [[++placeholder]]
Name: This is the label displayed in the "Name" column while viewing all system settings. This value can be localized (see below).
Field Type: There are currently 3 supported input types: TextField, TextArea, Yes/No
Namespace: as with Custom Manager Pages, the namespace defines a folder inside core/components/.
Area Lexicon Entry: this value affects the grouping of system settings; create multiple system settings that share the "Area Lexicon Entry" and they will be grouped together.
Value: The default value.
Description: This value can be localized (see below).

Localization¶

The values used to describe system settings can be optionally localized (i.e. translated) by referencing a specific localization file. The lexicon keys follow a specific format:

Name: setting_ + Key
Description: setting_ + Key + _desc

For example, if we look at Quip's [[++quip.emailsFrom]] setting, we see that it uses the the quip namespace. The expected folder structure is to look for localization files in the namespace's folder, then in a "lexicon" folder, then in folders divided by language codes, and then in the default.inc.php file, for example core/components/quip/lexicon/en/default.inc.php

In our Quip example, we see a name of setting_quip.emailsFrom and a description of setting_quip.emailsFrom_desc. These two values correspond to keys in the $_lang array inside of default.inc.php:

$_lang['setting_quip.emailsFrom'] = 'From Email';
$_lang['setting_quip.emailsFrom_desc'] = 'The email address to send system emails from.';

We encourage you to right-click an existing system setting and choose to "Update System Setting" to get an idea of how this works.

Getting a System Setting (programmatically)¶

To get a setting value from a snippet, plugin, or other PHP-code, you use the getOption function and passing it the unique key for the option, for example:

$siteStartId = $modx->getOption('site_start');

In WordPress, the comparable API function is get_option().

This function retrieves the value from the settings cache.

Saving a System Setting (programmatically)¶

Here's where things get a little bit more complicated: when we retrieve the value using getOption, we are retrieving the object from the settings cache. This has the distinct advantage of speed, but it means that we essentially have a read-only copy of the setting's value.

While there is a setOption method available; that only updates the in-memory setting cache.

This is for architectural reasons: the system settings are meant to defined as configurations, NOT runtime dynamic values. They are typically set at the time of install and then not often updated. However, there may be legitimate times when you need to update system settings programmatically, e.g. perhaps you have written a Custom Manager Page that offers a customized form to your users for its system settings.

If we want to update a system setting, we use the powerful xPDO getObject function. So let's revisit our retrieval of a simple site setting and compare it side by side with the more verbose (and more flexible) xPDO counterpart:

echo $modx->getOption('site_name');
// prints the same thing as this:
$setting = $modx->getObject('modSystemSetting', 'site_name');
if ($setting) {
    echo $setting->get('value');
}

The difference is that using getObject retrieves the object from the database uncached, and we can do far more things with an object, including saving that object. So here's how we would retrieve and save a system setting:

$setting = $modx->getObject('modSystemSetting', 'site_name');
$setting->set('value', 'My New Site Name');
$setting->save();

However, note that this does not clear the settings cache, so any subsequent calls to getOption will still return the older cached version of the setting.

To rectify this in MODX, you have to clear the cache. At the very least the system_settings cache, but if you're using the setting value in a snippet or other code affecting the front-end, the resource cache too:

$cacheRefreshOptions =  [
    'system_settings' => [],
    'resource' => [],
];
$modx->cacheManager->refresh($cacheRefreshOptions);

In WordPress, the comparable API function is update_option().

Retrieving a Setting's Meta Data¶

Once we start retrieving the Objects that represent the system settings instead of just their value, we can see all of the meta data for any given setting (i.e. all of the attributes). Look at this code as an example:

$Setting = $modx->getObject('modSystemSetting', 'site_name');
print_r( $Setting->toArray() );
/*
prints out something like this:
Array (
        [key] => site_name
        [value] => My Skiphop Site
        [xtype] => textfield
        [namespace] => core
        [area] => site
        [editedon] => 2010-10-24 21:53:55
)
*/

Once you understand how to manipulate objects using MODX and xPDO, you'll be able to retrieve and modify just about everything inside of MODX, because just about everything is an object.

If you have noticed in the GUI above, MODX allows for some very logical grouping of system settings. The most useful groupings are area and by the prefix of the key. Using xPDO's getCollection method, we can easily supply some search criteria to get the settings that we want.

Here's how we would pull up all settings from the 'Mail' area:

$relatedSettings = $modx->getCollection('modSystemSetting', array('area'=>'Mail'));
foreach ( $relatedSettings as $Setting ) {
        print $Setting->get('value');
}

This leads us naturally to one of xPDO's other features: the xPDOQuery object. We can use it to pass more complex criteria to our getCollection call. Here's how we would pull up all settings that used the prefix of "quip.":

$query = $modx->newQuery('modSystemSetting');
$query->where(array('key:LIKE' => 'quip.%') );
$relatedSettings = $modx->getCollection('modSystemSetting', $query);
foreach ( $relatedSettings as $Setting ) {
        print $Setting->get('value');
}

You may not have been expecting an introduction to xPDO while you were simply trying to retrieve and set system settings, but it's in there.

Creating a System Setting Programmatically¶

You may desire to create a System Setting programmatically in order to provide your users with a cleaner UX/UI. In your code, you can put something like the following:

$MySetting = $modx->newObject('modSystemSetting');
$MySetting->set('key', 'mykey');
$MySetting->set('value', 'my_value');
$MySetting->set('xtype', 'textfield');
$MySetting->set('namespace', 'my_namespace');
$MySetting->set('area', 'MyArea');
$MySetting->save();
// Clear the cache:
$cacheRefreshOptions =  array( 'system_settings' => array() );
$modx->cacheManager->refresh($cacheRefreshOptions);

Note that you must create lexicon entries that match your key name (see the section above on Localization):

Name: setting_ + Key
Description: setting_ + Key + _desc

So in this example, you would need to add the following lexicon entries to a lexicon that you have loaded:

$_lang['setting_mykey'] = 'Name of My Setting';
$_lang['setting_mykey_desc'] = 'Description of my key';

MODX will populate the values for the name and description based on those lexicon entries.

You may find it useful to reference your localized language strings inside your Templates or CMPs. You can do this via a lexicon tag, but you must specify the "setting" topic, e.g.

[[!%setting_emailsender? &topic=`setting` &namespace=`core` &language=`en`]]

Types of System Settings¶

The xtype attribute defines what type of field the GUI will use when rendering the interface for this field:

combo-boolean : stored values are 1 and 0; the GUI will display "Yes" and "No"
textfield : standard text field
textarea : standard textearea
text-password : standard password field (input is masked)
numberfield : used for entering numbers
modx-combo-language : allows user to select a language
modx-combo-source :
modx-combo-template : allows user to select a template
modx-combo-content-type : allows user to select a content type
modx-combo-charset : allows user to select a character set
modx-combo-rte : like the textarea, but with formatting controls
modx-combo-context : allows user to select a context
modx-combo-namespace : allows user to select a namespace
modx-combo-manager-theme : allows user to select a MODX manager theme

Settings List¶

A description of each setting follows: