Creating and Using Utility Snippets

How to create and use utility snippets in MODX Revolution


If you read the MODX Forums, you may occasionally see posts with a suggestion like "Just use a utility snippet," followed by some code. If you're not familiar with the concept you may not know what a "Utility Snippet" is, or how to use one. If you already know this, you can skip this article.


MODX logo

What is a Utility Snippet?

If you're not familiar with the term, you might think that a utility snippet is some special kind of snippet. It's not. It's just a regular snippet that's used in a different way. Most snippets in MODX are intended to run automatically when certain pages are visited. Wayfinder and getResources are obvious examples.

What's different about a utility snippet is that it's not intended to be run when someone visits a front-end page. Rather, intended to be run from the Manager, by a Manager user at a specific time, for a specific purpose.


Some Examples

You might want to use a utility snippet to add a batch of users to a specific user group. Another use would be to correct a spelling error or change some string (e.g., the name of an organization) that appears on many pages. In earlier versions of MODX, upgrading MODX could make some of your pages disappear because their uri field was empty. You could solve this by loading and saving every page, but using a utility snippet that loads and saves all pages would be a lot easier, especially if your site has a lot of pages. Now MODX has the "Refresh URIs" option (under Manage -> Clear Cache) on the top menu. If you still have an older version of MODX, the utility snippet might still come in handy when you upgrade. We'll use this case for an example.


Creating the Snippet

This is just like creating any snippet. Right-click on the Snippets folder in on the Elements tree in the Manager and select "New Snippet". Call the snippet RefreshUris and paste in this code:

$docs = $modx->getCollection('modResource');
$count = 0;
foreach ($docs as $doc) {
    $doc->save();
    $count++;
}

return '<h3>Refreshed ' . $count . ' Resources</h3>';

The code simply gets all the resources, then loops through them, saving each one. We added a counter and a success message so we can tell that the snippet has actually run successfully. It's a good practice to always have a utility snippet return some kind of success message. Otherwise, there's no easy way to tell if it has actually run.

This snippet is a good base for future utility snippets since it gets all resources on the site and saves them all. With small modifications (as we'll see in upcoming articles), you can add code to make changes to any of the resource fields before saving each resource.


Running the Snippet

In the very old days of MODX, there was actually a button on the Create/Edit Snippet panel that let you execute the snippet. I can see why it was removed, but it would be nice if it still existed and only appeared for members of the Administrator group. Instead, we just have to create a resource, put a tag for the snippet in the resource content, and visit the page.

Create a page called RefreshUris. Make sure it's unpublished so others can't run the snippet. In the Resource Content field, put this tag:

[[!RefreshUris]]

Save the resource. Now, just right-click on the resource in the tree and select "View" (or whatever it's called in your version of MODX). That's all there is to it. As an Administrator, you should have the view_unpublished permission. That will let you view the page from the Manager and have the snippet run without publishing the page.

Actually, it doesn't matter what the resource is called, so you might want to call it something like "Utility Snippet". That way you can use it to run any utility snippets just by changing the tag in the Resource Content field to the name of the snippet you want to run.


Coming Up

In the next article, we'll see a utility snippet designed to do search and replace operations on all your resources.


For more information on how to use MODX to create a web site, see my web site Bob's Guides, or better yet, buy my book: MODX: The Official Guide.

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)