In my previous article, we looked at how to access Setting values in various parts of a MODX site. In this one, we'll see some examples of practical uses for custom settings in MODX.
We'll look at examples of all Settings in MODX (System Settings, Context Settings, User Settings, and UserGroup settings). Some of the examples below are a little contrived. The point is not to use them directly, but to show some examples of what you can do with MODX settings.
When to use Settings
Before we dive into practical uses for settings, let's take a look at when to use settings vs Template Variables (TVs). Both of them store information and make it available on the site through tags, but they have different jobs.
The main job of Template Variables is to store information relevant to a specific web page (Resource). Template variables are tied to Templates (hence the name), and their available in any Resources that has the Template they belong to. But the data they store, is tied to a specific Resource. If you put a TV tag ([[*TvName]]) in the content field of a resource, the value that replaces it will come from the value of the TV for that resource. If no value is set for that resource, the value will be the default value for the TV itself (if one is set).
Settings, on the other hand, are available throughout the site. They can be accessed in Resources, Chunks, Templates, Snippets, and Plugins. They can also be placed in almost any kind of tag as well. So, for example, a property value in a snippet tag can be a setting tag like this:
[[SnippetName? &max_value=`[[++max_value]]` ]]
So the basic rule is that if you want to store a piece of information that's used for a single Resource, you can use a TV. If you want to store information that will be available in various places on the website, you want a setting. In both cases, this rule refers to small pieces of information, since larger pieces are better stored in a chunk or a file.
Custom Theme
In an earlier article, we create a custom System Setting with the key, custom_theme. You probably have a CSS file (or several) that controls the theme of your website, specifying the fonts, colors, images, and layout for the site. You might have more than one Theme (a dark and the light theme, for example). There are several themes available for the MODX Manager, and you might also have several themes for the front end of the site. Maybe your client would like you like to change the theme of the site occasionally to keep it from getting stale, so you create a series of CSS files with appropriate names. You could manually edit the sites main front-end Template to change the line that includes the CSS file, but another way to go would be to put the name of the css file in the custom_theme System Setting, and do this in the Template:
<link rel="stylesheet" href="[[++assets_url]]themes/[[++custom_theme]]">
Now, all you have to do to change the theme is edit the custom_theme System Setting.
Important for the following steps to work the custom_theme System Setting must already exist. When you create any setting other than a System Setting, the key has to be selected from a dropdown list. If the System Setting doesn't exist, you won't see it in the list.
Another important note: If you have put your System Setting in a separate namespace, as we did earlier in this series of articles, you will need to select that namespace in the setting-creation form in order for the key to appear in the dropdown list.
Context Setting
Suppose your client opens a branch of the company in a different country, and wants a different theme for that branch, even though the underlying site is the same. If you put the Resources for that branch in a different Context, you can create a new CSS file for the theme, put it in the themes directory, and create a Context Setting called custom_theme that will override the System Setting for Resources in the specified Context. You could also create a
Context Setting for the branch name or each branch.
User Group Setting
Imagine that the client now wants a different theme just for some of the site's users (this assumes that everyone logs in before viewing pages in the front end). You can put those users in a separate User Group and create a custom_theme UserGroup Setting for them. This will override both the System Setting and the Context Setting.
User Setting
Now some of the users in that group say they prefer the previous theme and the client wants to keep them happy. You could just remove them from the User Group, but maybe that group also controls what pages they can see, so you can't remove them. What you can do, though, is create a custom_theme User Setting with the name of the previous theme as its value (again, assuming that everyone logs in). This will override all other settings.
User's Choice
Now the client decides that all users should get to pick their own theme. You can create a simple form in the front end, that only logged-in user can see. The form presents a list of all the theme names as a set of radio options. The user picks one, and submits the form. A fairly simple snippet gets the submitted form with the desired theme $_SESSION array and does this:
$chosenTheme = $_SESSION['user_theme');
$userId = $modx->user->get('id');
$userSetting = $modx->getObject('modUserSetting', array('key' => 'custom_theme, 'user' => $userId));
if (!$userSetting) {
/* Setting does not exist, create it */
/* Get namespace of System Setting */
$systemSetting = $modx->getObject('modSystemSetting', array('key' => 'custom_theme'));
$ssNamespace = $systemSetting->get('namespace');
$userSetting = $modx->newObject('modUserSetting');
$userSetting->set('namespace', $ssNamespace);
$userSetting->set('key', 'custom_theme');
$userSetting->set('user', $userId);
}
/* Now the User Setting exists */
/* Set value to Chosen Theme */
$userSetting->set('value', $chosenTheme);
/* Save User Setting */
$userSetting->save();
Now every user gets the pick their preferred theme. The form itself can be created with FormIt, or simply created as a standard HTML Form. I would prefer to roll my own because the snippet could automatically generate the form using all the available themes, either by checking the themes/ directory, or from another textfield System Setting with a
comma-separated list of theme names.
Another way to go would be to put the form in a chunk and pull it onto the page at the top of the snippet using $modx->getChunk('ThemeChunk'), if the form has not been submitted yet.
The creation of the form is left as an exercise for the reader.
Another Example
Suppose the client's company has a number of executives, over time, people join the firm, get promoted, or retire, so the list needs to change. You could just create a chunk listing all the names, but often the names of the executives have to appear, individually, on various pages. In that case, it makes sense to create a System Setting for each executive position, with keys like ceo, cfo, cio, cto, vp_for_customer_support, vp_for_sales, vp_for_purchasing, and so on. Now, when the person in a given position changes, rather than editing the name wherever it appears, you can just change the appropriate System Setting. If new positions are created or removed, you can just create a new System Setting or remove an existing one.
If there are branches of the company in separate Contexts, you can just create Context Settings that will override the System Settings.
Wrapping Up
The use of settings in MODX Revolution it limited only by your imagination. In looking at other people's websites, I find the Template Variables tend to be overused and settings tend to be underused. Settings are generally much more efficient since MODX has to consult three separate tables to replace a TV tag, while all settings are pulled into a single PHP array and kept in memory for every page request. Accessing them is extremely fast.
Coming Up
In my next few articles, we'll look at how to hide specific items from view in the MODX Manager.
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.