Understanding MODX Settings

In this series of articles, we'll look at what MODX settings are, and how they're used. 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 (the things that begin with & in a snippet tag), 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 anywhere. They are often accessed in setting tags like this one:

[[++setting_name]]

In the example above, setting_name is the key for the setting. MODX will replace it with the setting's value. The tag could appear in the content of a Resource, in a Chunk, in a Template, or in some text returned from a snippet. It can also appear as part of the value of a TV, or a property used in a snippet tag. The setting can also be accessed in the code of a snippet or plugin, but not by using the tag above. We'll look at the various ways to use, and create setting in the articles of this series.

What kinds of Settings are there?

At present, MODX has four kinds of settings: System Settings, Context Settings, User 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 if you create the settings in the MODX Manager, those will be set automatically by MODX. 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)

The 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:

[[++some_setting]]

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.

Setting Types

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.

Coming Up

Since there are four kinds of settings, all accessed with the same type of MODX tag, you might wonder what 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.

Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.