Jump to main content Jump to doc navigation

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:

  1. User Setting
  2. Usergroup Setting
  3. Context Setting (Note that in the manager, the context is usually mgr)
  4. 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:

  1. access_category_enabled
  2. access_context_enabled
  3. access_resource_group_enabled
  4. allow_duplicate_alias
  5. allow_forward_across_contexts
  6. allow_manager_login_forgot_password
  7. allow_multiple_emails
  8. allow_tags_in_post
  9. allow_tv_eval
  10. anonymous_sessions
  11. archive_with
  12. automatic_alias
  13. automatic_template_assignment
  14. auto_check_pkg_updates
  15. auto_check_pkg_updates_cache_expire
  16. auto_isfolder
  17. auto_menuindex
  18. base_help_url
  19. blocked_minutes
  20. cache_action_map
  21. cache_alias_map
  22. cache_context_settings
  23. cache_db
  24. cache_db_expires
  25. cache_db_session
  26. cache_db_session_lifetime
  27. cache_default
  28. cache_disabled
  29. cache_format
  30. cache_handler
  31. cache_json
  32. cache_json_expires
  33. cache_lang_js
  34. cache_lexicon_topics
  35. cache_noncore_lexicon_topics
  36. cache_resource
  37. cache_resource_clear_partial
  38. cache_resource_expires
  39. cache_scripts
  40. cache_system_settings
  41. clear_cache_refresh_trees
  42. compress_css
  43. compress_js
  44. compress_js_groups
  45. compress_js_max_files
  46. concat_js
  47. confirm_navigation
  48. container_suffix
  49. context_tree_sortby
  50. context_tree_sortdir
  51. context_tree_sort
  52. context_tree_sort
  53. cultureKey
  54. custom_resource_classes
  55. date_timezone
  56. debug
  57. default_content_type
  58. default_context
  59. default_duplicate_publish_option
  60. default_media_source
  61. default_media_source_type
  62. default_per_page
  63. default_template
  64. default_username
  65. editor_css_path
  66. editor_css_selectors
  67. emailsender
  68. emailsubject
  69. enable_dragdrop
  70. enable_gravatar
  71. error_log_filename
  72. error_log_filepath
  73. error_page
  74. extension_packages
  75. failed_login_attempts
  76. feed_modx_news
  77. feed_modx_news_enabled
  78. feed_modx_security
  79. feed_modx_security_enabled
  80. fe_editor_lang
  81. filemanager_path
  82. filemanager_path_relative
  83. filemanager_url
  84. filemanager_url_relative
  85. forgot_login_email
  86. form_customization_use_all_groups
  87. forward_merge_excludes
  88. friendly_alias_lowercase_only
  89. friendly_alias_max_length
  90. friendly_alias_realtime
  91. friendly_alias_restrict_chars
  92. friendly_alias_restrict_chars_pattern
  93. friendly_alias_strip_element_tags
  94. friendly_alias_translit
  95. friendly_alias_translit_class
  96. friendly_alias_translit_class_path
  97. friendly_alias_trim_chars
  98. friendly_alias_urls
  99. friendly_alias_word_delimiters
  100. friendly_alias_word_delimiter
  101. friendly_urls
  102. friendly_urls_strict
  103. friendly_url_prefix
  104. friendly_url_suffix
  105. global_duplicate_uri_check
  106. hidemenu_default
  107. inherit_parent_template
  108. link_tag_scheme
  109. locale
  110. lock_ttl
  111. log_deprecated
  112. log_level
  113. log_snippet_not_found
  114. log_target
  115. mail_charset
  116. mail_encoding
  117. mail_smtp_auth
  118. mail_smtp_autotls
  119. mail_smtp_helo
  120. mail_smtp_hosts
  121. mail_smtp_keepalive
  122. mail_smtp_pass
  123. mail_smtp_port
  124. mail_smtp_prefix
  125. mail_smtp_single_to
  126. mail_smtp_timeout
  127. mail_smtp_user
  128. mail_use_smtp
  129. main_nav_parent
  130. manager_date_format
  131. manager_direction
  132. manager_favicon_url
  133. manager_html5_cache
  134. manager_js_cache_file_locking
  135. manager_js_cache_max_age
  136. manager_js_document_root
  137. manager_js_zlib_output_compression
  138. manager_language
  139. manager_lang_attribute
  140. manager_login_url_alternate
  141. manager_theme
  142. manager_time_format
  143. manager_use_fullname
  144. manager_week_start
  145. mgr_source_icon
  146. mgr_tree_icon_context
  147. modx_browser_default_sort
  148. modx_browser_default_viewmode
  149. modx_browser_tree_hide_files
  150. modx_browser_tree_hide_tooltips
  151. modx_charset
  152. new_file_permissions
  153. new_folder_permissions
  154. parser_recurse_uncacheable
  155. password_generated_length
  156. password_min_length
  157. phpthumb_allow_src_above_docroot
  158. phpthumb_cache_maxage
  159. phpthumb_cache_maxfiles
  160. phpthumb_cache_maxsize
  161. phpthumb_cache_source_enabled
  162. phpthumb_document_root
  163. phpthumb_error_bgcolor
  164. phpthumb_error_fontsize
  165. phpthumb_error_textcolor
  166. phpthumb_far
  167. phpthumb_imagemagick_path
  168. phpthumb_nohotlink_enabled
  169. phpthumb_nohotlink_erase_image
  170. phpthumb_nohotlink_text_message
  171. phpthumb_nohotlink_valid_domains
  172. phpthumb_nooffsitelink_enabled
  173. phpthumb_nooffsitelink_erase_image
  174. phpthumb_nooffsitelink_require_refer
  175. phpthumb_nooffsitelink_text_message
  176. phpthumb_nooffsitelink_valid_domains
  177. phpthumb_nooffsitelink_watermark_src
  178. phpthumb_zoomcrop
  179. preserve_menuindex
  180. principal_targets
  181. proxy_auth_type
  182. proxy_host
  183. proxy_password
  184. proxy_port
  185. proxy_username
  186. publish_default
  187. rb_base_dir
  188. rb_base_url
  189. request_controller
  190. request_method_strict
  191. request_param_alias
  192. request_param_id
  193. resource_tree_node_name
  194. resource_tree_node_name_fallback
  195. resource_tree_node_tooltip
  196. richtext_default
  197. search_default
  198. send_poweredby_header
  199. server_offset_time
  200. server_protocol
  201. session_cookie_domain
  202. session_cookie_httponly
  203. session_cookie_lifetime
  204. session_cookie_path
  205. session_cookie_secure
  206. session_enabled
  207. session_gc_maxlifetime
  208. session_handler_class
  209. session_name
  210. settings_version
  211. setting_static_elements_basepath
  212. show_tv_categories_header
  213. signupemail_message
  214. site_name
  215. site_start
  216. site_status
  217. site_unavailable_message
  218. site_unavailable_page
  219. static_elements_automate_chunks
  220. static_elements_automate_plugins
  221. static_elements_automate_snippets
  222. static_elements_automate_templates
  223. static_elements_automate_tvs
  224. static_elements_basepath
  225. static_elements_default_category
  226. static_elements_default_mediasource
  227. strip_image_paths
  228. symlink_merge_fields
  229. syncsite_default
  230. tree_default_sort
  231. tree_root_id
  232. tvs_below_content
  233. udperms_allowroot
  234. ui_debug_mode
  235. unauthorized_page
  236. upload_files
  237. upload_maxsize
  238. user_nav_parent
  239. use_alias_path
  240. use_browser
  241. use_context_resource_table
  242. use_editor
  243. use_frozen_parent_uris
  244. use_multibyte
  245. use_weblink_target
  246. welcome_action
  247. welcome_namespace
  248. welcome_screen
  249. welcome_screen_url
  250. which_editor
  251. which_element_editor
  252. xhtml_urls

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

  • modmore
  • Jens Wittmann – Gestaltung & Entwicklung
  • deJaya
  • Digital Penguin
  • Following Sea
  • YJ
  • Sepia River Studios
  • Dannevang Digital
  • eydolan
  • Nick Clark
  • Lefthandmedia
  • Murray Wood
  • Richard

Budget

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

Learn more