Display Chunk Info in the MODX Front End Part 1

In my previous article, we looked at how getOption() handles Snippet properties placed in a Snippet tag. In this one we’ll show how to display information about Chunks used in the content field of a Resource.

The Problem

MODX Community Forum user (henrik_nielsen) suggested the idea for this post, and the next one. He pointed out that new MODX users often have trouble finding out where a particular bit of content on a MODX web page comes from. I can report that experienced users can have the same problem.

The most common scenario happens when someone (for example, a client, your boss, or you) discovers that some content on the page is wrong and needs to be changed. If the content is in the Resource’s content field, it’s easy enough to find, but if the content is in a Chunk brought into the page via a Chunk tag, it can be a lot more difficult to find, especially on a large website with lots of Chunks.

Henrik suggested that it would be really useful if a message could be put into the page naming the Chunks involved and their categories.

I suggested that it might be possible to grab the page content during a MODX System Event and inject information about the Chunks it contains. I’ll get into this shortly, but first, a quick reminder about how MODX System Events work.

Working on a Solution

Because it’s difficult to tell exactly what information is available when a particular System Event fires, I planned to add code to the invokeEvent() method that wrote information about available variables and their values to the MODX Error Log. Using echo or print in a Plugin for debugging almost never works, but writing to the Error Log always does. Important: Never, ever, modify the MODX core code on a production site!

The first thing I discovered was a bunch of commented-out code that I had forgotten about. It was from the last time I tried to solve this problem (and failed miserably). I concluded at that time, that the task was impossible, but I decided to give it another shot.

The Solution

I’ll spare you the long list of things I tried that didn’t work. The problem is that there’s really no event where all the Chunk tags are present in the Resource content field, and you have the capability to change the page’s output. The Chunk tags are there in calls to OnParseDocument but not in the earliest calls. Worse yet, OnParseDocument is called many times during the processing of a Resource and messing with the page content at this point tends to blow it up.

I finally realized that the tags are available in the content field in the database record for the Resource. In the OnWebPageInit event, neither the tags, nor the Resource content is available, and you can’t call $modx->resource->getContent() without crashing the Plugin, but the Resource’s ID is available, in the $modx->resourceIdentifier variable.

That means we can get the Resource object from the DB based on its ID and store its content field in a variable called $content. Then, we collect the Chunk tags, create the notes, and use str_replace() to inject the notes containing the Chunks and their categories in that $content variable.

The MODX internal variable $modx-resource contains the real Resource being processed. The final step is to replace its content field with $modx->resource->setContent($content);. This is temporary, and has no effect on the original Resource in the database.

For some reason I don’t understand, you can’t call $modx->resource->getContent() at this point without crashing the Plugin, but you can call $modx->resource->setContent() successfully.

When it comes time to parse the document, our Chunk notes are still there, as are the Chunk tags, so the content of the Chunk appears after the note. We can also add an “end note” indicating the end of the Chunk content.

The Code

<?php
/**
 * ChunkInfo plugin for ChunkInfo extra
 *
 * Copyright 2023 Bob Ray <https://bobsguides.com>
 * Created on 12-15-2022
 *
 * @package chunkinfo
 */

/**
 * Description
 * -----------
 * The ChunkInfo Plugin shows information about chunk tags used in the current
 * resource when viewing it in the front end
 *
 * Variables
 * ---------
 * @var $modx modX
 * @var $scriptProperties array
 *
 * @package chunkinfo
 **/

 /* Usage
 *  ----- 
 * Attach the plugin to OnWebPageInit.
 * Create a Yes/No System setting 
 * with the key: show_chunk_info
 *  to turn the plugin on and off */

/* Check the System Setting and return if 
   it's not set */
$showChunkInfo = $modx->getOption('show_chunkinfo', null, false, true);

if (empty($showChunkInfo)) {
    return;
}

/* Set prefix so the plugin will work in
   both MODX 2 and MODX 2 */
$prefix = $modx->getVersionData()['version'] >= 3
    ? '\MODX\Revolution\\'
    : '';

/* Regex pattern to collect the chunk tags */
$pattern = '/\[\[!*\$([^]]+)]]/';

/* Note to put at the end of the cunk content */
$endNote = '[**** End of Chunk ****]';

/* Load CSS file */
$modx->regClientCSS(MODX_ASSETS_URL . 'components/chunkinfo/css/chunkinfo.css');

/* Get a copy of the current resource from the DB */
$doc = $modx->getObject($prefix . 'modResource', $modx->resourceIdentifier);

/* Set $modx->resource to our own doc */
$modx->resource = $doc;

/* Get the content field */
$content = $doc->getContent();

/* Find the chunk tags */
$success = preg_match_all($pattern, $content, $matches);

if ($success) { /* found at least one */
    $numMatches = count($matches[0]);
    for ($i = 0; $i < $numMatches; $i++) {
       $fullTag = $matches[0][$i];
       $chunkName = $matches[1][$i];

        /* Create the note */
       $note = getNote($modx, $chunkName, $prefix);

       /* Inject the note and end note into the content */
       $content = str_replace($fullTag, $note . $fullTag . $endNote, $content);
    }
    $modx->resource->setContent($content);
}
return;

/* Function to create the note with
   the name and category of the chunk */

function getNote($modx, $chunkName, $prefix) {
    $catName = 'None';

    /* Remove output modifiers, if any */
    if (strpos((string)$chunkName, ":") !== false) {
        $temp = explode(":", $chunkName);
        $chunkName = $temp[0];
    }

    /* Remove properties, if any */
    if (strpos((string)$chunkName, "?") !== false) {
        $temp = explode("?", $chunkName);
        $chunkName = $temp[0];
    }
    $chunk = $modx->getObject($prefix . 'modChunk',
        array('name' => $chunkName));

    /* Get category name and chunk id */
    if ($chunk) {
        $cat = $chunk->getOne('Category');
        if ($cat) {
            $catName = $cat->get('category');
        }
    }

    return '<span class="chunk_note">[Chunk: ' . $chunkName .
        ' -- Category: ' . $catName . ']</span>';
}

How It Works

The comments in the code above explain much of how it works, but let’s look at some of the details.

Turning the Plugin on and Off

Changing the value of the show_chunkinfo System Setting (which you must create) from “Yes” to “No” will turn the Chunk on and off. So will right-clicking on the Plugin in the tree and disabling it (or using the checkbox when editing the Plugin). If you disable it in the tree, you need to clear the cache before it will take effect. You may also need to do that when changing the System Setting.

The Regular Expression

This regular expression (regex, for short) pattern is used to grab the Chunk tags:

$pattern = '/\[\[!*\$([^\]]+)]]/';

The slashes at each end just mark the beginning and end of the expression. The backslashes in the pattern are to escape the character that follows, so \[ is a literal opening bracket. Without the backslash, the regular expression parser would assume they surround a character class. \] is a literal closing bracket, and \$ is a literal dollar sign.

The * character denotes 0 or more of the previous character, so the beginning of the expression says to look for [[ followed by 0 or more ! characters, followed by a literal dollar sign: '\$'. So far, the regex would match the sequences [[!$ and [[$.

The parentheses mark the part of the pattern we want to capture: the name of the Chunk. Inside them is a character class, '[^]]+'. This is a little odd, the character class, marked by the outer '[]' characters, matches at least one or more characters (the + sign) that are not a ']'. A ^ character at the beginning of a character class can be read as “not”. In other words, any character(s) except the ones listed between the brackets. In this case only one character, \] is listed (a literal closing bracket), so the part in the parentheses starts after the $ and ends just before the Chunk tag's first closing ']'. We add the ]] at the end so the full pattern will match the whole Chunk tag.

preg_match_all()

This line collects the Chunk tags:

preg_match_all($pattern, $content, $matches);

The $pattern is our regular expression (regex). The $content is the Resource’s content field. The $matches variable is a “reference” variable. The code of the preg_match_all() function will modify it, and the modification will persist after the call is finished.

The $matches array will be an array of arrays. Each inner array will have to members, the first is the whole tag it matched. The second is the part in the parentheses. So with two Chunk tags anywhere in the content like this:

[[Chunk1]]
[[Chunk2]]

The $matches array would look like this:

array(
    0 => array(
        0 => '[[Chunk1]]',
        1 => '[[Chunk2]]', 
    ),
    1 => array(
        0 => 'Chunk1',
        1 => 'Chunk2', 
    ),
)

The first array above contains the two full Chunk tags. The second one contains just the names of the Chunks.

Once we have the Chunk name ($matches[1][$i]), we call the getNote() function, which gets the actual Chunk from the db, finds its category, and returns HTML code like this:

<span class="chunk_note">[Chunk: MyChunk -- Category: SomeCategory]</span>

In our loop, we step through the $matches array. For each Chunk, we get the Chunk name and the full tag. We use the Chunk name to create our note then we replace the full tag in the content with this sequence: note, full tag, end note.

So for a Chunk with the content <p>Actual Chunk Content</p>, this:

[[SomeChunk]]

becomes something like this when displayed in the front end:

[Chunk: SomeChunk -- Category: SomeCategory]
Actual chunk content
[**** End of Chunk ****]

Output Modifiers and Properties

If the Chunk has an output modifier or properties, they will be caught by our regular expression as part of the Chunk name. The regex could be modified to prevent that, but the expression would be a little harder to explain. It’s easy enough to remove them before trying to get the Chunk by name. That’s what this code does for output modifiers, which always start with :

/* Remove output modifiers, if any */
    if (strpos((string)$chunkName, ":") !== false) {
        $temp = explode(":", $chunkName);
        $chunkName = $temp[0];
    }

Explode takes a delimiter as its first argument. It splits the string (the second argument) into an array, breaking it at each delimiter, and removing the delimiter.

If the regex grabs this string as the Chunk name:

SomeChunk:some output modifier

The array returned from explode would be

$temp = array(
   0 => 'SomeChunk'
   1 => 'some output modifier'
)

So, $temp[0] will always be the actual Chunk name.

The code that follows that will do the same thing for properties, which always start with ?.

If explode doesn’t find the delimiter, it puts the whole string in the first member of the array, so $temp[0] will still be the actual Chunk name.

We’ll see a slightly more elegant way to handle this in my next article.

CSS

With the CSS file, you can do something like this to make the notes stand out:

.chunk_note {
    color: red;
    background-color: lightyellow;
}

Drawbacks

When Henrik tested the code, he pointed out that it only recognizes Chunks in the Resource’s content field. It doesn’t spot Chunks in the Template of the page. Solving that is even more complicated than what you see above. It involves attaching two more System Events to the Plugin and creating a $_SESSION variable to hold the Chunk information between events. We’ll look at that in my next article.

I haven’t tested this, but I suspect that if the Chunk tag contains output modifiers that contain Chunk tags, things may go south in a hurry, though I’m pretty sure that doesn’t happen very often.

Safety

You might be worried that messing with $modx->resource and the database will cause problems, but the database is read, but never modified, so the “real” Resource can’t be modified by any of the code above. Once the Plugin is turned off, everything will behave as it normally would because the Resource isn’t modified, and no MODX core code has been changed.

Warning

IMPORTANT: The code of this Plugin won’t harm the Resources it processes, but because it messes with the parsing process, it will interfere with some other Plugins and Custom Manager Pages (CMPS). I’m not aware of any permanent trouble it will cause, but it will keep RefreshCache and some other Extras from working properly.

Turn this Plugin on, find out which chunk holds the information you need to edit, and turn it off. Don’t leave it enabled.

---

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.