1. Getting Started
      1. Video Quick-Start Series
      2. Server Requirements
        1. MySQL 5.0.51 Issues
      3. Installation
        1. Basic Installation
          1. MODx Revolution on Debian
          2. Problems with WAMPServer 2.0i
          3. Lighttpd Guide
          4. Installation on a server running ModSecurity
          5. MODX and Suhosin
          6. Nginx Server Config
        2. Successful Installation, Now What Do I Do?
        3. Successful Installation, Now What Do I Do?
        4. Advanced Installation
        5. Git Installation
        6. Command Line Installation
          1. The Setup Config Xml File
        7. Troubleshooting Installation
        8. Using MODx Revolution from SVN
      4. An Overview of MODX
        1. Glossary of Revolution Terms
          1. Explanation of Directory Structure
        2. Roadmap
        3. MODX Revolution Framework Structure Ideology
        4. What's New in 2.3
    2. FAQs & Troubleshooting
      1. CMP Development FAQs & Troubleshooting
    3. Making Sites with MODX
      1. Structuring Your Site
        1. Resources
          1. Content Types
          2. Named Anchor
          3. Static Resource
          4. Symlink
            1. Using Resource Symlinks
          5. Weblink
        2. Templates
        3. Chunks
        4. Using Snippets
      2. Tag Syntax
      3. Customizing Content
        1. Template Variables
          1. Creating a Template Variable
          2. Adding a Custom TV Type - MODX 2.2
          3. Bindings
            1. CHUNK Binding
            2. DIRECTORY Binding
            3. EVAL Binding
            4. FILE Binding
            5. INHERIT Binding
            6. RESOURCE Binding
            7. SELECT Binding
          4. Template Variable Input Types
          5. Template Variable Output Types
            1. Date TV Output Type
            2. Delimiter TV Output Type
            3. HTML Tag TV Output Type
            4. Image TV Output Type
            5. URL TV Output Type
          6. Adding a Custom TV Input Type
          7. Adding a Custom TV Output Type
          8. Creating a multi-select box for related pages in your template
          9. Accessing Template Variable Values via the API
        2. Properties and Property Sets
        3. Input and Output Filters (Output Modifiers)
          1. Custom Output Filter Examples
      4. Commonly Used Template Tags
        1. Date Formats
    4. Administering Your Site
      1. Settings
        1. System Settings
          1. access_category_enabled
          2. date_timezone
          3. access_context_enabled
          4. access_resource_group_enabled
          5. allow_duplicate_alias
          6. allow_forward_across_contexts
          7. allow_multiple_emails
          8. allow_tags_in_post
          9. archive_with
          10. automatic_alias
          11. auto_check_pkg_updates
          12. auto_check_pkg_updates_cache_expire
          13. auto_menuindex
          14. base_help_url
          15. blocked_minutes
          16. cache_action_map
          17. cache_context_settings
          18. cache_db
          19. cache_db_expires
          20. cache_db_session
          21. cache_default
          22. cache_disabled
          23. cache_format
          24. cache_handler
          25. cache_json
          26. cache_json_expires
          27. cache_lang_js
          28. cache_lexicon_topics
          29. cache_noncore_lexicon_topics
          30. cache_resource
          31. cache_resource_expires
          32. cache_scripts
          33. cache_system_settings
          34. clear_cache_refresh_trees
          35. compress_css
          36. compress_js
          37. concat_js
          38. container_suffix
          39. cultureKey
          40. custom_resource_classes
          41. default_per_page
          42. default_template
          43. editor_css_path
          44. editor_css_selectors
          45. emailsender
          46. emailsubject
          47. enable_dragdrop
          48. error_page
          49. extension_packages
          50. failed_login_attempts
          51. feed_modx_news
          52. feed_modx_news_enabled
          53. feed_modx_security
          54. feed_modx_security_enabled
          55. fe_editor_lang
          56. filemanager_path
          57. filemanager_path_relative
          58. filemanager_url
          59. filemanager_url_relative
          60. forgot_login_email
          61. friendly_alias_lowercase_only
          62. forward_merge_excludes
          63. friendly_alias_max_length
          64. friendly_alias_restrict_chars
          65. friendly_alias_restrict_chars_pattern
          66. friendly_alias_strip_element_tags
          67. friendly_alias_translit
          68. friendly_alias_translit_class
          69. friendly_alias_translit_class_path
          70. friendly_alias_trim_chars
          71. friendly_alias_urls
          72. friendly_alias_word_delimiter
          73. friendly_alias_word_delimiters
          74. friendly_urls
          75. friendly_url_prefix
          76. friendly_url_suffix
          77. global_duplicate_uri_check
          78. hidemenu_default
          79. link_tag_scheme
          80. mail_charset
          81. mail_encoding
          82. mail_smtp_auth
          83. mail_smtp_helo
          84. mail_smtp_hosts
          85. mail_smtp_keepalive
          86. mail_smtp_pass
          87. mail_smtp_port
          88. mail_smtp_prefix
          89. mail_smtp_single_to
          90. mail_smtp_timeout
          91. mail_smtp_user
          92. mail_use_smtp
          93. manager_date_format
          94. manager_direction
          95. manager_favicon_url
          96. manager_language
          97. manager_lang_attribute
          98. manager_theme
          99. manager_time_format
          100. context_tree_sort
          101. context_tree_sortby
          102. context_tree_sortdir
          103. session_enabled
          104. upload_files
          105. modx_charset
          106. new_file_permissions
          107. new_folder_permissions
          108. password_generated_length
          109. password_min_length
          110. phpthumb_allow_src_above_docroot
          111. phpthumb_cache_maxage
          112. phpthumb_cache_maxfiles
          113. phpthumb_cache_maxsize
          114. phpthumb_cache_source_enabled
          115. phpthumb_document_root
          116. phpthumb_error_bgcolor
          117. phpthumb_error_fontsize
          118. phpthumb_error_textcolor
          119. phpthumb_far
          120. phpthumb_imagemagick_path
          121. phpthumb_nohotlink_enabled
          122. phpthumb_nohotlink_erase_image
          123. phpthumb_nohotlink_text_message
          124. phpthumb_nohotlink_valid_domains
          125. phpthumb_nooffsitelink_enabled
          126. phpthumb_nooffsitelink_erase_image
          127. phpthumb_nooffsitelink_require_refer
          128. phpthumb_nooffsitelink_text_message
          129. phpthumb_nooffsitelink_valid_domains
          130. phpthumb_nooffsitelink_watermark_src
          131. phpthumb_zoomcrop
          132. principal_targets
          133. proxy_auth_type
          134. proxy_host
          135. proxy_password
          136. proxy_port
          137. proxy_username
          138. publish_default
          139. rb_base_dir
          140. rb_base_url
          141. request_controller
          142. request_param_alias
          143. request_param_id
          144. resource_tree_node_name
          145. resource_tree_node_tooltip
          146. richtext_default
          147. search_default
          148. server_offset_time
          149. server_protocol
          150. session_cookie_domain
          151. session_cookie_lifetime
          152. session_cookie_path
          153. session_cookie_secure
          154. session_handler_class
          155. session_name
          156. settings_version
          157. signupemail_message
          158. site_name
          159. site_start
          160. site_status
          161. site_unavailable_message
          162. site_unavailable_page
          163. strip_image_paths
          164. symlink_merge_fields
          165. tree_default_sort
          166. tree_root_id
          167. tvs_below_content
          168. udperms_allowroot
          169. ui_debug_mode
          170. unauthorized_page
          171. upload_maxsize
          172. use_alias_path
          173. use_browser
          174. use_editor
          175. use_multibyte
          176. welcome_screen
          177. which_editor
          178. which_element_editor
          179. xhtml_urls
      2. Using Friendly URLs
      3. Contexts
        1. Creating a Subdomain from a Folder using Virtual Hosts
        2. Using One Gateway Plugin to Manage Multiple Domains
      4. Customizing the Manager
        1. Customizing the Manager via Plugins
        2. Form Customization Profiles
        3. Form Customization Sets
          1. Customizing Tabs via Form Customization
          2. MODX GitHub Contributor's Guide
        4. Manager Templates and Themes
      5. MODX GitHub Integrator's Guide
      6. Security
        1. Hardening MODX Revolution
        2. Policies
          1. ACLs
          2. Permissions
            1. Permissions - Administrator Policy
            2. Permissions - Resource Policy
          3. PolicyTemplates
        3. Resource Groups
        4. Roles
        5. Security Standards
        6. Security Tutorials
          1. More on the Anonymous User Group
          2. Creating a Second Super Admin User
          3. Giving a User Manager Access
          4. Making Member-Only Pages
          5. Restricting an Element from Users
        7. Troubleshooting Security
          1. Resetting a User Password Manually
        8. User Groups
        9. Users
      7. Installing a Package
        1. Troubleshooting Package Management
      8. Upgrading MODX
        1. Upgrading to Revolution 2.0.5
        2. Upgrading from 2.0.x to 2.1.x
        3. Upgrading from Versions Earlier than 2.0.5
        4. Upgrading to 2.2.x
        5. Upgrading to Revolution 2.0.0-rc-2
        6. Troubleshooting Upgrades
        7. Upgrading from MODx Evolution
          1. Functional Changes from Evolution
      9. Moving Your Site to a New Server, or to Root from Subfolder
      10. Media Sources
        1. Adding a Media Source
        2. Assigning Media Sources to TVs
        3. Media Source Types
          1. Media Source Type - File System
          2. Media Source Type - S3
        4. Securing a Media Source
          1. Creating a Media Source for Clients Tutorial
      11. Dashboards
        1. Assigning a Dashboard to a User Group
        2. Creating a Dashboard Widget
        3. Dashboard Widget Types
          1. Dashboard Widget Type - File
          2. Dashboard Widget Type - HTML
          3. Dashboard Widget Type - Inline PHP
          4. Dashboard Widget Type - Snippet
        4. Managing Your Dashboard
    5. Developing in MODX
      1. Code Standards
      2. Overview of MODX Development
        1. Developer Introduction
          1. Getting Started Developing
        2. Extras Directories
        3. Setting up a Development Environment
      3. Basic Development
        1. Static Elements
        2. Plugins
          1. System Events
            1. OnMODXInit
            2. OnFileManagerBeforeUpload
            3. OnFileManagerDirCreate
            4. OnFileManagerDirRemove
            5. OnFileManagerDirRename
            6. OnFileManagerFileCreate
            7. OnFileManagerFileRemove
            8. OnFileManagerFileRename
            9. OnFileManagerFileUpdate
            10. OnPackageInstall
            11. OnPackageUninstall
            12. OnPackageRemove
            13. OnBeforeCacheUpdate
            14. OnBeforeChunkFormDelete
            15. OnBeforeChunkFormSave
            16. OnBeforeDocFormDelete
            17. OnBeforeDocFormSave
            18. OnBeforeEmptyTrash
            19. OnBeforeManagerLogin
            20. OnBeforeManagerLogout
            21. OnBeforeManagerPageInit
            22. OnBeforePluginFormDelete
            23. OnBeforePluginFormSave
            24. OnBeforeSaveWebPageCache
            25. OnBeforeSnipFormDelete
            26. OnBeforeSnipFormSave
            27. OnBeforeTempFormDelete
            28. OnBeforeTempFormSave
            29. OnBeforeTVFormDelete
            30. OnBeforeTVFormSave
            31. OnBeforeUserActivate
            32. OnBeforeUserFormDelete
            33. OnBeforeUserFormSave
            34. OnBeforeWebLogin
            35. OnBeforeWebLogout
            36. OnCacheUpdate
            37. OnCategoryBeforeRemove
            38. OnCategoryBeforeSave
            39. OnCategoryRemove
            40. OnCategorySave
            41. OnChunkBeforeRemove
            42. OnChunkBeforeSave
            43. OnChunkFormDelete
            44. OnChunkFormPrerender
            45. OnChunkFormRender
            46. OnChunkFormSave
            47. OnChunkRemove
            48. OnChunkSave
            49. OnContextBeforeRemove
            50. OnContextBeforeSave
            51. OnContextFormPrerender
            52. OnContextFormRender
            53. OnContextRemove
            54. OnContextSave
            55. OnDocFormDelete
            56. OnDocFormPrerender
            57. OnDocFormRender
            58. OnDocFormSave
            59. OnDocPublished
            60. OnDocUnPublished
            61. OnEmptyTrash
            62. OnFileManagerUpload
            63. OnHandleRequest
            64. OnInitCulture
            65. OnLoadWebDocument
            66. OnLoadWebPageCache
            67. OnManagerAuthentication
            68. OnManagerLogin
            69. OnManagerLoginFormPrerender
            70. OnManagerLoginFormRender
            71. OnManagerLogout
            72. OnManagerPageAfterRender
            73. OnManagerPageBeforeRender
            74. OnManagerPageInit
            75. OnPageNotFound
            76. OnPageUnauthorized
            77. OnParseDocument
            78. OnPluginBeforeRemove
            79. OnPluginBeforeSave
            80. OnPluginEventRemove
            81. OnPluginFormDelete
            82. OnPluginFormPrerender
            83. OnPluginFormRender
            84. OnPluginFormSave
            85. OnPluginRemove
            86. OnPluginSave
            87. OnPropertySetBeforeRemove
            88. OnPropertySetBeforeSave
            89. OnPropertySetRemove
            90. OnPropertySetSave
            91. OnResourceGroupBeforeRemove
            92. OnResourceGroupBeforeSave
            93. OnResourceGroupRemove
            94. OnResourceGroupSave
            95. OnRichTextBrowserInit
            96. OnRichTextEditorInit
            97. OnRichTextEditorRegister
            98. OnSiteRefresh
            99. OnSiteSettingsRender
            100. OnTemplateVarBeforeRemove
            101. OnTemplateVarBeforeSave
            102. OnTemplateVarRemove
            103. OnTemplateVarSave
            104. OnUserActivate
            105. OnUserBeforeRemove
            106. OnUserBeforeSave
            107. OnUserChangePassword
            108. OnUserFormDelete
            109. OnUserFormSave
            110. OnUserNotFound
            111. OnUserRemove
            112. OnUserSave
            113. OnWebAuthentication
            114. OnWebLogin
            115. OnWebLogout
            116. OnWebPageComplete
            117. OnWebPageInit
            118. OnWebPagePrerender
        3. Snippets
          1. Adding CSS and JS to Your Pages Through Snippets
          2. How to Write a Good Chunk
          3. How to Write a Good Snippet
          4. Templating Your Snippets
        4. xPDO
      4. Advanced Development
        1. Caching
          1. Setting up Memcache in MODX
        2. Custom Manager Pages
          1. Custom Manager Pages in 2.3
          2. Actions and Menus
            1. Action List
          3. Custom Manager Pages Tutorial
          4. MODExt
            1. MODx.combo.ComboBox
            2. MODx.Console
            3. MODx.FormPanel
            4. MODx.grid.Grid
            5. MODx.grid.LocalGrid
            6. MODx.msg
            7. MODx.tree.Tree
            8. MODx.Window
            9. MODExt Tutorials
              1. 1. Ext JS Tutorial - Message Boxes
              2. 2. Ext JS Tutorial - Ajax Include
              3. 3. Ext JS Tutorial - Animation
              4. 4. Ext JS Tutorial - Manipulating Nodes
              5. 5. Ext JS Tutorial - Panels
              6. 7. Ext JS Tutoral - Advanced Grid
              7. 8. Ext JS Tutorial - Inside a CMP
            10. MODExt MODx Object
        3. Custom Resource Classes
          1. Creating a Resource Class
            1. Creating a Resource Class - Step 2
            2. Creating a Resource Class - Step 3
            3. Creating a Resource Class - Step 4
        4. Extending modUser
        5. From the Command Line (CLI)
        6. Internationalization
          1. Adding a Translation
        7. MODX Services
          1. modFileHandler
          2. modMail
          3. modRegistry
        8. Namespaces
        9. Package Management
          1. Package Dependencies
          2. Creating a 3rd Party Component Build Script
          3. Providers
          4. Transport Packages
        10. Using runProcessor
        11. Validating Requests: Tokens and Nonces
        12. Developing RESTful APIs
      5. Other Development Resources
        1. Summary of Legacy Code Removed in 2.1
        2. API Reference
        3. Class Reference
          1. modResource
            1. modResource.isMember
          2. modChunk
            1. modChunk.getContent
            2. modChunk.setContent
          3. modUser
            1. modUser.addSessionContext
            2. modUser.changePassword
            3. modUser.endSession
            4. modUser.getSessionContexts
            5. modUser.getSettings
            6. modUser.hasSessionContext
            7. modUser.isAuthenticated
            8. modUser.isMember
            9. modUser.loadAttributes
            10. modUser.removeSessionContext
            11. modUser.removeSessionContextVars
            12. modUser.removeSessionCookie
          4. modX
            1. modX.addEventListener
            2. modX.checkForLocks
            3. modX.checkSession
            4. modX.executeProcessor
            5. modX.getAuthenticatedUser
            6. modX.getCacheManager
            7. modX.getChildIds
            8. modX.getChunk
            9. modX.getConfig
            10. modX.getContext
            11. modX.getEventMap
            12. modX.getLoginUserID
            13. modX.getLoginUserName
            14. modX.getParentIds
            15. modX.getParser
            16. modX.getPlaceholder
            17. modX.getRegisteredClientScripts
            18. modX.getRegisteredClientStartupScripts
            19. modX.getRequest
            20. modX.getResponse
            21. modX.getService
            22. modX.getSessionState
            23. modX.getTree
            24. modX.getUser
            25. modX.getVersionData
            26. modX.handleRequest
            27. modX.hasPermission
            28. modX.initialize
            29. modX.invokeEvent
            30. modX.lexicon
            31. modX.makeUrl
            32. modX.parseChunk
            33. modX.regClientCSS
            34. modX.regClientHTMLBlock
            35. modX.regClientScript
            36. modX.regClientStartupHTMLBlock
            37. modX.regClientStartupScript
            38. modX.reloadConfig
            39. modX.removeAllEventListener
            40. modX.removeEventListener
            41. modX.runProcessor
            42. modX.runSnippet
            43. modX.sendError
            44. modX.sendErrorPage
            45. modX.sendForward
            46. modX.sendRedirect
            47. modX.sendUnauthorizedPage
            48. modX.setDebug
            49. modX.setPlaceholder
            50. modX.setPlaceholders
            51. modX.switchContext
            52. modX.toPlaceholder
            53. modX.toPlaceholders
            54. modX.unsetPlaceholder
            55. modX.unsetPlaceholders
        4. Loading MODX Externally
        5. Reserved Parameters
    6. Case Studies and Tutorials
      1. Developing an Extra in MODX Revolution
        1. Developing an Extra in MODX Revolution, Part II
        2. Developing an Extra in MODX Revolution, Part III
      2. Developing an Extra in MODX Revolution - MODX 2.1 and Earlier
        1. Developing an Extra in MODX Revolution, Part II - MODX 2.1 and Earlier
        2. Developing an Extra in MODX Revolution, Part III - MODX 2.1 and Earlier
      3. PHP Coding in MODx Revolution, Pt. I
        1. PHP Coding in MODx Revolution, Pt. II
        2. PHP Coding in MODx Revolution, Pt. III
      4. Using Custom Database Tables in your 3rd Party Components
      5. Creating a Blog in MODx Revolution
      6. Loading Pages in the Front-End via AJAX and jQuery Tabs
      7. Reverse Engineer xPDO Classes from Existing Database Table
      8. Integrating a Template into MODX Tutorial
      9. Quick and Easy MODX Tutorials
        1. Automated Server-Side Image Editing
      10. Adding Custom Fields to Manager Forms
      11. Create a Multilingual Website with migxMultiLang
      12. Managing Resources and Elements via SVN
    7. MODX Community Information
      1. Becoming a Core Contributor
      2. Filing Bug Reports
      3. Getting a MODx Account
      4. Using GitHub

System Settings

Last edited by Luk on May 25, 2014.

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.

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

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_multiple_emails
  7. allow_tags_in_post
  8. archive_with
  9. auto_check_pkg_updates
  10. auto_check_pkg_updates_cache_expire
  11. auto_menuindex
  12. automatic_alias
  13. base_help_url
  14. blocked_minutes
  15. cache_action_map
  16. cache_context_settings
  17. cache_db
  18. cache_db_expires
  19. cache_db_session
  20. cache_default
  21. cache_disabled
  22. cache_format
  23. cache_handler
  24. cache_json
  25. cache_json_expires
  26. cache_lang_js
  27. cache_lexicon_topics
  28. cache_noncore_lexicon_topics
  29. cache_resource
  30. cache_resource_expires
  31. cache_scripts
  32. cache_system_settings
  33. clear_cache_refresh_trees
  34. compress_css
  35. compress_js
  36. context_tree_sort
  37. context_tree_sortby
  38. context_tree_sortdir
  39. concat_js
  40. container_suffix
  41. cultureKey
  42. custom_resource_classes
  43. default_per_page
  44. default_template
  45. editor_css_path
  46. editor_css_selectors
  47. emailsender
  48. emailsubject
  49. enable_dragdrop
  50. error_page
  51. extension_packages
  52. failed_login_attempts
  53. fe_editor_lang
  54. feed_modx_news
  55. feed_modx_news_enabled
  56. feed_modx_security
  57. feed_modx_security_enabled
  58. filemanager_path
  59. filemanager_path_relative
  60. filemanager_url
  61. filemanager_url_relative
  62. forgot_login_email
  63. forward_merge_excludes
  64. friendly_alias_lowercase_only
  65. friendly_alias_max_length
  66. friendly_alias_restrict_chars
  67. friendly_alias_restrict_chars_pattern
  68. friendly_alias_strip_element_tags
  69. friendly_alias_translit
  70. friendly_alias_translit_class
  71. friendly_alias_translit_class_path
  72. friendly_alias_trim_chars
  73. friendly_alias_urls
  74. friendly_alias_word_delimiter
  75. friendly_alias_word_delimiters
  76. friendly_url_prefix
  77. friendly_url_suffix
  78. friendly_urls
  79. global_duplicate_uri_check
  80. hidemenu_default
  81. link_tag_scheme
  82. mail_charset
  83. mail_encoding
  84. mail_smtp_auth
  85. mail_smtp_helo
  86. mail_smtp_hosts
  87. mail_smtp_keepalive
  88. mail_smtp_pass
  89. mail_smtp_port
  90. mail_smtp_prefix
  91. mail_smtp_single_to
  92. mail_smtp_timeout
  93. mail_smtp_user
  94. mail_use_smtp
  95. manager_date_format
  96. manager_direction
  97. manager_favicon_url
  98. manager_lang_attribute
  99. manager_language
  100. manager_theme
  101. manager_time_format
  102. modx_charset
  103. new_file_permissions
  104. new_folder_permissions
  105. password_generated_length
  106. password_min_length
  107. phpthumb_allow_src_above_docroot
  108. phpthumb_cache_maxage
  109. phpthumb_cache_maxfiles
  110. phpthumb_cache_maxsize
  111. phpthumb_cache_source_enabled
  112. phpthumb_document_root
  113. phpthumb_error_bgcolor
  114. phpthumb_error_fontsize
  115. phpthumb_error_textcolor
  116. phpthumb_far
  117. phpthumb_imagemagick_path
  118. phpthumb_nohotlink_enabled
  119. phpthumb_nohotlink_erase_image
  120. phpthumb_nohotlink_text_message
  121. phpthumb_nohotlink_valid_domains
  122. phpthumb_nooffsitelink_enabled
  123. phpthumb_nooffsitelink_erase_image
  124. phpthumb_nooffsitelink_require_refer
  125. phpthumb_nooffsitelink_text_message
  126. phpthumb_nooffsitelink_valid_domains
  127. phpthumb_nooffsitelink_watermark_src
  128. phpthumb_zoomcrop
  129. principal_targets
  130. proxy_auth_type
  131. proxy_host
  132. proxy_password
  133. proxy_port
  134. proxy_username
  135. publish_default
  136. rb_base_dir
  137. rb_base_url
  138. request_controller
  139. request_param_alias
  140. request_param_id
  141. resource_tree_node_name
  142. resource_tree_node_tooltip
  143. richtext_default
  144. search_default
  145. server_offset_time
  146. server_protocol
  147. session_cookie_domain
  148. session_cookie_lifetime
  149. session_cookie_path
  150. session_cookie_secure
  151. session_enabled
  152. session_handler_class
  153. session_name
  154. settings_version
  155. signupemail_message
  156. site_name
  157. site_start
  158. site_status
  159. site_unavailable_message
  160. site_unavailable_page
  161. strip_image_paths
  162. symlink_merge_fields
  163. tree_default_sort
  164. tree_root_id
  165. tvs_below_content
  166. udperms_allowroot
  167. ui_debug_mode
  168. unauthorized_page
  169. upload_maxsize
  170. use_alias_path
  171. use_browser
  172. use_editor
  173. use_multibyte
  174. welcome_screen
  175. which_editor
  176. which_element_editor
  177. xhtml_urls

Comment Policy

These comments are not for usage questions or support. See below for support options.

Comments intended add specific value for other users with this document are welcome! Have a suggestion to improve this document? Suggest an edit (requires GitHub account). Have suggestions for code changes or feature requests? Submit to the Revolution project at GitHub..

Support Options

If you need assistance, you can get it via the MODX Forums or the MODX Community Slack.

Suggest an edit to this page on GitHub (Requires GitHub account. Opens a new window/tab) or become an editor of the MODX Documentation.