System Settings

Creating new System Settings (via the GUI)

Parameters
Localization

Using System Settings in your Code

Getting a System Setting (programmatically)
Saving a System Setting (programmatically)
Retrieving a Setting's Meta Data

Retrieving a list of Related Settings
Creating a System Setting Programmatically
Settings List

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.

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.

Using System Settings in your Code

Frequently, you'll want to be able to retrieve the values for your system settings in your Snippets or Plugins. There's more information on this page.

Getting a System Setting (programmatically)

In a nutshell, you do it using 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.

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 default to 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:

print $modx->getOption('site_name');

// prints the same thing as this:

$Setting = $modx->getObject('modSystemSetting', 'site_name');
print $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 2.0.x, you have to clear the entire cache, including your page cache. Clearing your entire cache frequently could slow down your system because it would keep having to rebuild it:

// clear cache in MODx 2.0.x
$modx->cacheManager->clearCache();

MODx 2.1.x offers more granular caching, which helps us in this case:

// clear cache in MODx 2.1.x
$cacheRefreshOptions =  array( 'system_settings' => array() );
$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.

Retrieving a list of Related Settings

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

Settings List

A description of each setting follows:

Settings