Set Resource Fields and TV Values in a Plugin

In this article, we’ll take a look at using a Plugin to perform actions whenever a Resource is saved. But first, a quick refresher on how Plugins work.

Plugins

As MODX goes about its business there are certain points where MODX fires a System Event, using code like this:

$modx->invokeEvent('EventName', $options);

The invokeEvent() method is part of the $modx class. The event name is something like OnDocFormSave, or OnUserFormSave. The $options variable is an array holding information that Plugins attached to that event might need to do their jobs. For example, the Resource object itself, or a flag indicating whether the Resource is a new one, or an existing one being updated (more on this in a bit).

Specific events are “fired” when a Resource is saved, deleted, added to a Resource group, removed from a Resource group, or duplicated. There are other similar events for users and other objects or processes in MODX.

Plugins are just bits of PHP code that “listen” for particular System Events to be “invoked”. When that happens, the Plugin code executes. When the Plugin code is finished, control returns to MODX, which gets on with whatever it’s doing.

In other words, when an event is invoked, MODX checks to see whether any Plugins are “listening” for that event. Any that are listening are sent the information in the $options array, which they use while running their code.

Plugins and Resources

There are lots of things you might want to do when a Resource is saved in the Manager. You might want to adjust or duplicate a field, say to make the description field match the introtext field. You might also want to adjust a Resource field based on the value of a TV, adjust a TV based on a Resource field, or adjust one TV based on the value of one or more other TVs.

The following example Plugins would all be connected to the OnDocFormSave event. To use them, paste the code into a Plugin and, on the “System Events” tab, check the box next to OnDocFormSave. Then, save the Plugin. In a Plugin attached to that event, the Resource being saved is always available as the $resource variable.

Example OnDocFormSave Plugins

Here’s a simple example that just writes whatever is in the introtext (summary) field to the description field, but only if the Resource is new and the description field is empty:

/* Do nothing if it's not a new resource */
if ($mode !== modSystemEvent::MODE_NEW) {
    return '';
}

$introText = $resource->get('introtext');
if (empty($resource->get('description') {
    $resource->set('description', $introText);
}
$resource->save();
return '';

Dogs and Cats

Imagine that you want to set a particular TV value for new Resources created directly under a particular folder, but only if certain other conditions are true. Let’s say your site has a listing of pets available for adoption. We’ll ignore the fact that you should really use a custom database table for this information and say that you have TVs for things like the breed, weight, and name of the animal. You want to set a TV called “Size” to Large if the animal’s weight is over 45 pounds, but only for dogs—cats have a different weight limit (15). You can tell whether the animal is a dog or cat by checking the ID of its parent. In our example, the “Dogs” folder has an ID of 12 and the “Cats” folder has an ID of 22.

You could just enter the Size TV manually every time a dog or cat is entered into the system, but why not let the computer do the work for you with this Plugin attached to OnDocFormSave:

/* Do nothing if it's not a new resource */
if ($mode !== modSystemEvent::MODE_NEW) {
    return;
}
$dogFolderId = 12;
$catFolderId = 22;

/* Get the animal's weight */
$weight = $resource->getTVValue('weight');

/* Handle dogs */
if ($resource->get('parent') == $dogFolderId) {
    if ( (integer) $weight > 45) {
        $resource->setTVValue('Size', 'Large');
    }
}

/* Handle cats */
if ($resource->get('parent') == $catFolderId) {
    if ( (integer) $weight > 15) {
        $resource->setTVValue('Size', 'Large');
    }
}

return '';

Notice that we don’t have to save the Resource in the example above, because we haven’t changed any of its fields.

The code above could be compressed into fewer lines with some PHP tricks. It might be a few milliseconds faster, but it would be much more difficult to understand and modify.

Obviously, you’d probably want to have more weight classes (i.e., Small, Medium, Large), but it would be easy to add code for them. You might also want to remove the code at the top of the Plugin that prevents the Plugin from executing for existing animals. That way, the weight description TV value would change when you save the Resource any time that the animal’s weight changed enough to put them in a different weight class.

More Fun With Plugins

You can perform a lot of useful tricks with Plugins. Plugins, like the ones in this article, can not only save you valuable time, they have the potential to speed up page loads dramatically. Any processing that can be performed once when a Resource is saved, will save time if that processing then doesn’t have to be performed every time the page is loaded.

---

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.