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

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:

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:

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:

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:

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:

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.

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.":