In this series of articles, we'll look at what MODX settings are, and how they're used. Quite a while ago, I did an article on using
$modx->getOption() to get the contents of both settings and snippet or plugin properties. We'll review some of that information later in this series.
What's a Setting?
MODX settings are really just a list of keys and values. You give MODX the key and it gives you back the value. In fact, they are very similar to snippet properties, which are also lists of keys and values. The difference is that snippet properties are directly available only inside the snippet (in the
$scriptProperties array). Settings, on the other hand, can be accessed with setting tags:
In the example above,
setting_name is the key for the setting. MODX will replace it with the setting's value.
What kinds of Settings are there?
At present, MODX has four kinds of settings: System Settings, Context Settings, User Group Settings (often called just Group Settings), and User Settings. All of them take the same form and have most of the same database fields.
All settings have the following fields:
- key (string)
- name (string)
- description (String)
- namespace (string)
- xtype (string)
- area (string)
- editedon (timestamp)
- value (string)
Some of the settings have extra fields, but in most cases, to use a setting, all you care about are the first two:
value. Here's a list of the extra fields:
- Context Settings:
context_key(e.g., 'web' or 'mgr')
- User Group Settings:
group(the ID of the group)
- User Settings:
user(the ID of the user)
key is how you refer to the setting when you want its value. If you want to display the value of a setting with the key,
some_setting, you can use this code just about anywhere:
The setting tag can be used in a Template or chunk, in any of the text fields of the resource -- pretty much anything that will be displayed in the browser. Setting tags can be used inside snippet tags or even inside another setting tag.
Setting tags always begin with
++. The tag on the page will be replaced by whatever is in the
value field of the setting.
Remember that placeholder tags in MODX begin with a single
+ and resource tags begin with a single
*. It's easy to get them confused.
You can probably guess what the various types of settings contain, but here's a quick summary. System Settings are generic settings meant to be available throughout the site. Context Settings apply everywhere in the particular context they belong to — they are ignored in any other context. User Group Settings apply to all members of the User Group they are assigned to. User Settings apply only to one specific user.
As I mentioned above, User Group Settings are sometimes referred to as "Group Settings". The term "group" in MODX can refer to either a User Group or a Resource Group, so it's more correct to use the full name. There are no "Resource Group Settings", at present, but there could be in the future.
Since there are four kinds of settings, all accessed with the same type of MODX tag, you might wonder which one's value you'll get if more than one setting has the same name (or maybe you already know). We'll look at that question in the next article.
Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)