Bob's Guides

CacheMaster Plugin Tutorial

If you use this extra and like it, please consider donating. The suggested donation for this extra is $5.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-premium extras with a clear conscience.

Overview

On a large site, MODX's default behavior of clearing the entire cache for all Resources and Elements whenever you save one can really slow things down for your visitors. The CacheMaster Plugin for MODX Revolution allows you to have the cache cleared for a single Resource or Element when you save it, without clearing anything else.

CacheMaster will also allow you to have the "Empty Cache" checkbox unchecked by default for Resources and/or selected elements.

(Jump to Properties Table.)

Installing CacheMaster

Go to System | Package Management on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository (AKA Web Transport Facility). Put CacheMaster in the search box and press Enter. Click on the "Download" button, and once the package is downloaded, click on the "Back to Package Manager" button. That should bring you back to your Package Management grid. Click on the "Install" button next to CacheMaster in the grid. The CacheMaster package should now be installed.

Using CacheMaster

The default behavior of MODX is to refresh the entire site cache for all Resources and Elements if the "Empty Cache" checkbox is checked and for no Resources or Elements (not even the current one) if the checkbox is not checked. Cachemaster, if the Plugin is enabled, will always clear the cache for the object you are saving if its type is selected in the CacheMaster properties, regardless of whether the "Empty Cache" checkbox is checked or not.

CacheMaster only executes when you update an existing object. It will not do anything at all when you create a new Resource or Element (i.e., MODX will refresh the whole site cache normally when you save, unless you manually uncheck the "Empty Cache") checkbox.

CacheMaster has six properties that determine which Elements it operates on and whether it operates on Resources (see table below). In addition to those properties it has the &uncheckEmptyCache, property, which controls the "Empty Cache" checkbox on the Create/Edit panel for Resources and Elements.

If none of the six object selection properties is selected, CacheMaster will do nothing (this is equivalent to disabling the plugin). By default, only Resources are selected.

In addition to the selection properties, CacheMaster also has the &uncheckEmptyCache property. The default value of the property is Yes. With that setting, the "Empty Cache" checkbox on the Settings tab will be unchecked when you edit any objects selected by the other properties. If you check the checkbox before saving the Resource or Element, the whole site cache will be cleared (as it would be if the plugin were not installed.) If you leave it unchecked, only the cache for the current object will be cleared. The site cache will not be cleared (except when saving Templates — see the note above about Templates).

If &uncheckEmptyCache is set to No, CacheMaster will not uncheck the "Empty Cache" checkbox — when the Create/Edit panel is loaded, but it will still clear the individual object cache for selected objects if you uncheck the box before saving.

To put that all another way, when CacheMaster is enabled, saving a Resource or Element with the "Empty Cache" checkbox checked will always clear the entire cache. Saving a Resource or Element with the "Empty Cache" checkbox unchecked will always clear the cache for the Resource or Element you are saving but only for objects selected with the other properties. The "&uncheckEmptyCache" property, if set, just unchecks the "Empty Cache" checkbox for you with any selected objects as the form is loaded in the Manager.

Two Ways to Use CacheMaster

The options described above give you two basic ways to use the plugin, depending on the value of the &uncheckEmptyCache property. Remember that without the plugin, MODX refreshes the whole site cache if the "Empty Cache" checkbox is checked. If the checkbox is not checked, MODX doesn't touch the cache at all. The old version of the object remains in the cache.

With CacheMaster installed, and the &uncheckEmptyCache set to No, MODX will clear the whole cache if you leave the checkbox checked. If you uncheck it before saving, however, CacheMaster will clear the cache for the object you are saving if you have selected it with one of the other properties. This means that if you select all the objects in the CacheMaster properties, you can uncheck the checkbox yourself and the cache for the object you are saving will always be cleared.

With CacheMaster installed, and the &uncheckEmptyCache set to Yes, the behavior is exactly the same as just described, except that the checkbox is unchecked for you when the Create/Edit panel for any selected object is loaded.

Setting the CacheMaster Properties

To set the CacheMaster properties, edit the Plugin, and set the properties on the Properties Tab. Don't forget to save the Plugin. Note that if you change the values of any properties, they will be set back to their defaults if you upgrade CacheMaster. To avoid that, create a property set for the Plugin.

Creating a Property Set for the CacheMaster Plugin

You can edit the CacheMaster plugin's default properties grid, but it's STRONGLY recommend that you NOT do this. It is a bad practice because your values will all be overwritten when you upgrade the plugin.

The recommended method is to create a custom Property Set. Here's how:

1. In the tree, click on Elements | Plugins | CacheMaster
2. Click on the properties tab
3. On the right side, click on "Add Property Set""
4. Check the checkbox for "Create New Property Set""
5. Give the set a name (e.g. CacheMasterProperties) and a description
6. Click on the "Save" button
7. You should see the Property Set name above the grid
8. (If you see 'Default' instead of your property set name, click on it and select your Property Set from the drop-down list)
9. Edit any properties you want to change (the names of the changed items will appear in green after you save the set)
10. Click on the "Save Property Set" button
11. Click on the "System Events" tab
12. Scroll down to any checked events
13. Double-click on the "Property Set" field
14. Select your Property Set on the drop-down list
15. Click on the "Save" button

The plugin will then use your custom Property Set to override any values in the default set.

Important: When changing plugin options, be sure to select your custom Property Set before editing. On the "Properties" tab of the plugin, click on the word "Default" just above the grid and select your Property Set. Be careful not to edit the Default Property Set. The Default Properties are locked to remind you.

Things to Remember

Failing to clear the site cache will speed up page loads for your site, but if you're not careful, it can leave you with pages that are not up-to-date. If, for example, you change the Menu Title of a page, any cached Wayfinder menus will show the old name until the site cache is cleared.

Similarly, if you change the code of a snippet, plugin, or chunk, and save it using CacheMaster with the "Empty Cache" checkbox unchecked, the cached version of the object itself will be removed, but any cached resources with cached tags for the object will still show the results from the old version of the object.

Objects in MODX are highly interdependent, and it can be difficult to guess what the effects of not clearing the cache will be. That's why the default behavior in MODX is to refresh the entire cache.

When in doubt, you can always clear the entire site cache Manually using the Manager's Top Menu.

CacheMaster will clear the cache for a single Resource or Element if you use the MODX Revolution default cache setup. It is designed to work with other caching strategies, but has not been tested with them.

CacheMaster Properties

Copyright © 2011-2025
Bob Ray