Easily Toggle MODX System Settings with a Custom Widget

The Problem

A while back, a MODX forum user (scoder) asked for an easier way to toggle the site_status System Setting. If this is something you do often, it's a pain to have to go to the System Settings grid, find the setting, and change its value over and over. In This article we'll look at a fairly simple widget that will let you toggle the site_status setting with a single click. The article is based on an idea from Susan Sottwell.

Although we're using the site_status setting as an example, this widget could be used to toggle the value of any Yes/No System Setting

The Concept

The idea is to embed a simple HTML form in the widget. When the "Submit" button is clicked, a bit of PHP code toggles the System Setting. When the setting is changed, so is the text of the "Submit" button.

Creating the Widget

Here are the steps for creating the Widget:

1. Go to System (gear icon) -> Dashboards
2. Click on the Widgets tab
3. Click on the "Create New Widget" tab
4. Fill in the Name: Toggle Site Status
5. Set the size to "Half"
6. Set the Widget Type to Inline PHP Widget
7. Paste this code into the Widget Content Field:<br />

<?php
$output = '';

if (isset($_POST['submitVarToggle'])) {
    /* Submit button clicked */

    /* Set the System Setting Object */
    $setting = $modx->getObject('modSystemSetting', array('key' => 'site_status'));
    $status = $setting->get('value');
    $status = $status ? '0' : '1';
    $setting->set('value', $status);
    $setting->save();

    /* Clear the System Settings cache */
    $cm = $modx->getCacheManager();
    $cm->refresh(array('system_settings' => array()));
}  else {
    $status = $modx->getOption('site_status');
}

/* Set a variable for the text of Submit button based on the current status */
$statusMessage = $status? ' Take Site Offline ' : ' Bring Site Online ';

/* Display the form */
$output .= '
    <form action = "" method="post">

    <input style="padding:10px" type="submit" name="submitVarToggle" value="' . $statusMessage . '" />

    </form>';

return $output;

8. Click on the "Save" button
9. Click on the "Close" button

The Code

The code above is fairly self-explanatory. The only thing that might be confusing are the two lines that actually do the toggling. The first one toggles the System Setting, the second one toggles the text of the Submit button:

$newStatus = empty($status) ? '1' : '0';
$statusMessage = $status? ' Take Site Offline ' : ' Bring Site Online ';

Both lines use the PHP ternary operator. Basically, they tell PHP that if the part before the question mark is true, use the value just after the question mark. If not, use the value of the part after the colon. This is just a shorthand way of expressing an if else statement. The following code would be the equivalent of the first line:

if ($status) {
   $status = '0';
} else {
    $status = '1';
}

The second line is equivalent to this code:

if ($status) {
    $statusMessage = ' Take Site Offline ';
} else {
    $statusMessage = ' Bring Site Online ';
}

If you prefer, you can use the two if/else code above in place of the two ternary statements. The only significant effect will be to make the code longer, and easier to read for people not familiar with the ternary statement.

Connecting the Widget to the Dashboard

Now that we've created the Widget, we need to attach it to a dashboard, so it will show up in the Manager. Here are the steps for that:

1. Click on the "Dashboards" tab
2. Right-click on the Dashboard you want to add the widget to and select "Update Dashboard"
3. Click on "Place Widget"
4. Use the drop-down menu to select your widget
5. Click on the "Save" button in the dialog
6. Click on the "Save" button at the upper right

Notice that at the end of the procedure above, you have to click "Save" twice. Once to confirm the widget placement, and again to save the widget and the placement together.

Adapting the Widget to other System Settings

This widget can be used to toggle any Yes/No System Setting. The only things we'd need to change are the name of the setting and the two text messages for the Submit button.

The widget could also be adapted to other types of settings. To do that, you'd just need to change the object retrieved from modSystemSetting to modContextSetting, modUserSetting, or modUserGroupSetting.

Enhancements

The only drawback of our widget is that when the button is clicked, it forces a reload of the Manager page. This could be avoided, but it would make things a bit more complicated. We'd have to create a namespace for our widget, a controller to display the form, and a processor to toggle the setting. We'd call the processor with an Ajax call triggered by the click on the Submit button. If your site has a lot of resources, reloading the Manager page takes a long time, and the Settings will be changed frequently, this might be worth the effort. For most cases, though, the simple form above should be adequate.

If you have a lot of System Settings to control, you should consider installing Mark Hamstra's excellent ClientConfig extra. It takes a little effort to set up, but it provides a very nice interface for modifying System Settings.

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.