Using MODX Settings in Code

Using settings in the PHP code of a snippet or plugin


In the last article, we looked at a concrete example using a User Setting to personalize the look of your site. In this one, we'll look at how to to access MODX settings in PHP code.

There may be times when you can't accomplish what you want just by using a setting tag. There may also be times when you can accomplish what you want with a tag and one or more output modifiers, but would rather have the speed of a dedicated snippet. In those cases, you need to know how to handle settings in PHP code. In this article we'll use the custom_theme user setting from the last article as an example.

MODX logo

A Hybrid Solution

Once way of using setting values in a snippet is to send them as properties in the snippet tag. Suppose that you want to present a chunk called chunk1 only to users who have selected the midnight theme. We'll use a snippet called AddChunk and send the theme setting as a property called themeName. The chunk will return nothing if that's not the user's selected theme.

[[!AddChunk? &themeName=`[[++custom_theme]]` ]]

Now the snippet:

/* AddChunk snippet */
$theme = $modx->getOption('themeName', $scriptProperties, '');

$output = '';
if ($theme === 'midnight') {
    $output = $modx->getChunk('chunk1');
}

return $output;

Getting the Value of a Setting from the DB

The example above is slightly inefficient if all you're doing it showing chunk1 to users who have selected the midnight theme. We know MODX is going to have to get the chunk, but it takes time to parse the snippet tag and create the $scriptProperties array. Another way to go would be to get the value of the User Setting directly in the snippet.

[[!AddChunk]]
/* AddChunk snippet */
$output = '';
if ($modx->getOption('custom_theme') === 'midnight') {
    $output = $modx->getChunk('chunk1');
}
return $output;

In this second example, we're getting the value of the custom_theme setting directly from the database. If it's 'midnight', we're returning the chunk. If not we return nothing. MODX doesn't have to parse any properties in the tag, and since there aren't any, it doesn't have to fill in the scriptProperties array.

Notice that we don't have to tell MODX what kind of setting we want the value of. We'll automatically get whatever setting has the highest priority (in this case, a User Setting). As you recall from the previous articles, System Settings have the lowest priority, Context Settings come next, then User Group Settings, and finally, with the highest priority among the settings, User Settings.

Another difference between the two methods is that our getOption() call now has just one argument. We don't send it the second argument (the $scriptProperties array, because we just want the value of a setting.

We could have added $scriptProperties as the second argument. If we had, getOption() would check for a property called &custom_theme before looking at the settings. Any property with that name would override the value of any settings, including a User Setting. This would be be true if that property was in the snippet tag, in the default properties of the snippet, or in a property set referenced in the snippet tag. If it was in more then one of those places, the property specified in the tag would have the highest priority, the property set would be second, and the default properties would have the lowest priority. Again, though, any of the three would override the User Setting.


Switching Based on a Setting Value

The examples above are a little simplistic, since (if you recall) we had three possible themes (midnight, seaview, and lakeview) and we only dealt with one of them. Suppose you want to display a different chunk for each theme? PHP's switch statement is perfect for that:

[[!AddChunk]]
/* AddChunk snippet */

$chunkName = '';

$themeName = $modx->getOption('custom_theme');

switch ($themeName) {
    case 'midnight':
        $chunkName = 'chunk1';
        break;

    case 'lakeview':
        $chunkName = 'chunk2';
        break;

    case 'seaview':
        $chunkName = 'chunk3';
        break;

    default:
        $chunkName = 'defaultChunk';
}

return $modx->getChunk($chunkName);

Now our snippet will return the appropriate chunk based on the custom_theme User Setting. Notice that we've added a default case and a default chunk to use when there is no User Setting. This would be unnecessary if we created a custom_theme System Setting containing the name of the default theme to use. The getOption() call would get the System Setting's value if no User Setting existed for the current user.


Coming Up

It may have occurred to you that there's an even easier and more efficient way to do what the code samples above are doing. It uses a method I like to call "fortuitous naming" (Patent Pending ;) ). We'll look at that 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.)



Comments (0)


Please login to comment.

  (Login)