Settings
What are Settings?
Settings are site-wide variables that can be used by either the MODx Core or by 3rd-Party Components to provide site, context, or user-level customization. The trick here is the override behavior that applies in the hierarchy: Contextual Settings (if present), override any of the System Settings. User Settings (if present) override any of the Context or System settings obeying the hierarchy of System -> Context -> User
See the following for more information:
Usage
They can be referenced at any point via their Tag, for example, for the 'site_start' Setting:
[[++site_start]]
System Settings can be overridden by Context Settings, which are specific to each Context. Context Settings can in turn be overridden by User Settings.
The hierarchy to remember is:
System Setting -> Context Setting -> User Setting
Let's say I set the System Setting named 'use_editor' to 0. However, I created a Context Setting called 'use_editor' for the 'mgr' context and set it to 1. This would mean that any time I'm in the mgr context, the setting would be 1, overriding the System Setting.
Further, I've got a user named 'johndoe' who I don't want to use the editor. I create a User Setting 'use_editor' for his user and set it to 0. Now, John Doe's "use_editor" setting will be 0, overriding the Context Setting.
Settings can also be specific to Namespaces, as well. This allows you to easily group your settings for each of your different Components.
Retrieving Settings in PHP
Getting settings is simple in MODx Revolution; simply use getOption. For example, to get the setting 'site_start', simply:
$siteStartId = $modx->getOption('site_start');
Now, all settings are overridable by Context and User, as described above, and getOption respects that. So, if in the above code example, if you had set site_start as a Context Setting that overrode the System Setting, getOption will respect that - but only if you're executing the PHP in that Context that has the Setting.
For example, if I were using that code block in a Context called 'boo', and I had added a Context Setting for site_start in the 'boo' Context, and set it to 3, the above code would output '3'.
Now if I were in the 'web' context, and site_start was still '1' (from the System Setting), getOption would return 1.
Default values with getOption
getOption supports 3 parameters:
1. The key of the setting
2. An array to search first before looking for the setting
3. A default value should the setting not be found.
So, for example, if I were in a Snippet and wanted some default properties at the top, I could use getOption. Snippets automatically pass in an array of all the Properties attached to that snippet (or specified in the Tag call) via the $scriptProperties array. So, you can use that array to check for default properties. This example sets a default value to the 'showPublished' property should it not be specified:
$showPublished = $modx->getOption('showPublished',$scriptProperties,true);
Now, assuming the Snippet doesnt have showPublished as a default property, if you called the Snippet via the tag call:
[[mySnippet]]
showPublished will be set to true. If it did have the default Property attached to it that set the value to 0, or the showPublished property was specified as 0 in the tag, then showPublished would be 0.
Additional Information
- Only use getOption if you're reading an existing setting from the DB, not if you need to update the option.
- getOption uses the settings cache (it's much faster)
- getOption will also check User -> Context -> System settings (allowing you to override system settings with context and further with user settings)
See Also
- System Settings
- access_category_enabled
- access_context_enabled
- access_resource_group_enabled
- allow_duplicate_alias
- allow_forward_across_contexts
- allow_multiple_emails
- allow_tags_in_post
- archive_with
- auto_check_pkg_updates
- auto_check_pkg_updates_cache_expire
- auto_menuindex
- automatic_alias
- base_help_url
- blocked_minutes
- cache_action_map
- cache_context_settings
- cache_db
- cache_db_expires
- cache_db_session
- cache_default
- cache_disabled
- cache_format
- cache_handler
- cache_json
- cache_json_expires
- cache_lang_js
- cache_lexicon_topics
- cache_noncore_lexicon_topics
- cache_resource
- cache_resource_expires
- cache_scripts
- cache_system_settings
- clear_cache_refresh_trees
- compress_css
- compress_js
- concat_js
- container_suffix
- cultureKey
- custom_resource_classes
- default_per_page
- default_template
- editor_css_path
- editor_css_selectors
- emailsender
- emailsubject
- enable_dragdrop
- error_page
- extension_packages
- failed_login_attempts
- fe_editor_lang
- feed_modx_news
- feed_modx_news_enabled
- feed_modx_security
- feed_modx_security_enabled
- filemanager_path
- filemanager_path_relative
- filemanager_url
- filemanager_url_relative
- forgot_login_email
- forward_merge_excludes
- friendly_alias_lowercase_only
- friendly_alias_max_length
- friendly_alias_restrict_chars
- friendly_alias_restrict_chars_pattern
- friendly_alias_strip_element_tags
- friendly_alias_translit
- friendly_alias_translit_class
- friendly_alias_translit_class_path
- friendly_alias_trim_chars
- friendly_alias_urls
- friendly_alias_word_delimiter
- friendly_alias_word_delimiters
- friendly_url_prefix
- friendly_url_suffix
- friendly_urls
- global_duplicate_uri_check
- hidemenu_default
- link_tag_scheme
- mail_charset
- mail_encoding
- mail_smtp_auth
- mail_smtp_helo
- mail_smtp_hosts
- mail_smtp_keepalive
- mail_smtp_pass
- mail_smtp_port
- mail_smtp_prefix
- mail_smtp_single_to
- mail_smtp_timeout
- mail_smtp_user
- mail_use_smtp
- manager_date_format
- manager_direction
- manager_favicon_url
- manager_lang_attribute
- manager_language
- manager_theme
- manager_time_format
- modx_charset
- new_file_permissions
- new_folder_permissions
- password_generated_length
- password_min_length
- phpthumb_allow_src_above_docroot
- phpthumb_cache_maxage
- phpthumb_cache_maxfiles
- phpthumb_cache_maxsize
- phpthumb_cache_source_enabled
- phpthumb_document_root
- phpthumb_error_bgcolor
- phpthumb_error_fontsize
- phpthumb_error_textcolor
- phpthumb_far
- phpthumb_imagemagick_path
- phpthumb_nohotlink_enabled
- phpthumb_nohotlink_erase_image
- phpthumb_nohotlink_text_message
- phpthumb_nohotlink_valid_domains
- phpthumb_nooffsitelink_enabled
- phpthumb_nooffsitelink_erase_image
- phpthumb_nooffsitelink_require_refer
- phpthumb_nooffsitelink_text_message
- phpthumb_nooffsitelink_valid_domains
- phpthumb_nooffsitelink_watermark_src
- phpthumb_zoomcrop
- principal_targets
- proxy_auth_type
- proxy_host
- proxy_password
- proxy_port
- proxy_username
- publish_default
- rb_base_dir
- rb_base_url
- request_controller
- request_param_alias
- request_param_id
- resource_tree_node_name
- resource_tree_node_tooltip
- richtext_default
- search_default
- server_offset_time
- server_protocol
- session_cookie_domain
- session_cookie_lifetime
- session_cookie_path
- session_cookie_secure
- session_handler_class
- session_name
- settings_version
- signupemail_message
- site_name
- site_start
- site_status
- site_unavailable_message
- site_unavailable_page
- strip_image_paths
- symlink_merge_fields
- tree_default_sort
- tree_root_id
- tvs_below_content
- udperms_allowroot
- ui_debug_mode
- unauthorized_page
- upload_maxsize
- use_alias_path
- use_browser
- use_editor
- use_multibyte
- welcome_screen
- which_editor
- which_element_editor
- xhtml_urls
Suggest an edit to this page on GitHub (Requires GitHub account. Opens a new window/tab).