Display Chunk Info in the MODX Front End Part 2

In the previous article, we looked at how to display information about which Chunks contain some of the content of the current page in the front end of the site. The code in that article only displayed information for Chunks in the Resource’s content field. In this one we’ll see how to do the same for Chunks contained in the page’s Template. We’ll also make some improvements to the Plugin.

See the previous article for a description of the problem we’re trying to solve and the approach we’re taking.

The Problems

The code in the previous article will never display information about Chunk tags in the page’s Template. That’s because it executes when the OnWebPageInit event fires. At that point the template hasn’t been retrieved and isn’t available to us. That means we have to connect the Plugin to two other events in addition to OnWebPageInit (OnParseDocument and OnDocFormPrerender).

The code in the previous article that creates the notes that appear above the chunks’ content is a little ugly. It would be nice to enclose it in a function, especially since we now need to create a note in more than one place in the code. It would be embarrassing to have that same code appear twice in the script, and it would make the script harder to maintain.

There’s a catch, though.

Non-functional Functions

When a Plugin is connected to more than one event, it can’t use a function without some special treatment. When the second event fires, the Plugin is executed again, but it’s during the same request, so the Plugin crashes badly when the function is declared for the second time. When I say “crashes badly”—there’s no output at all. Your looking at the white screen of death, and there’s nothing in the MODX error log.

One solution is to wrap the whole function in something like this:

if (! function_exists('getNote')) {
   /* Function goes here */
}

Another method would be to create a class with just the method we need, but it’s a little extreme to create a class for such a small task—and wouldn’t be useful in any other project.

A third, method would be to use a Tpl Chunk for the note, but then we wouldn’t get to use an anonymous function.

We’re going to create our notes with an anonymous function, also called a “closure” (though not by me). If you look at the full code of the Plugin later in this article, you’ll see that a variable ($getNote) is set to the function itself. This is an anonymous function, so called because it has no name. It’s created as a temporary function, and it disappears when it goes out of scope, so it solves the re-declaration problem:

$getNote = function ($modx, $chunkName, $prefix) {
   /* Function code here */
} 

Since the function has no name, we call it like this:

$note = $getNote($modx, $chunkName, $prefix);

Where Can We Get the Tags Contained in the Template

The only place I could find where the Template’s Chunk tags are available is in the first pass of the OnParseDocument event. Now, we have two more problems. First, OnParseDocument fires many times as the Resource is parsed. So how can we make sure our code only executes on the first pass.

Second, at the time of OnParseDocument, there’s no way to change the output that will appear when the finished document is displayed.

To solve these problems, we create a $_SESSION variable containing the Chunk tag information. It’s called chunk_matches and has two functions. First, our OnParseDocument code only executes if the $_SESSION variable doesn’t exist. That means the code will only execute on the first pass of OnParseDocument. The second function of the $_SESSION variable is to hold the Chunk information until later, when OnDocFormPrerender fires. At that point, we can change the final output of the page using the information we’ve saved.

That creates yet another problem. In 'OnDocFormPrerender', the tags in the Template have already been replaced by the Chunk’s content, so we can’t use the Chunk tag to do the replacement and inject our notes. Instead, we get the Chunk’s content from the database, process it with the MODX parser, and search for that.

We want the fully parsed Chunk. If the Chunk contains Snippet tags or other Chunk tags. We want those to be parsed because the fully parsed Chunk is what will be present when OnDocFormPrerender fires. Otherwise, our search will fail.

Finally, in OnDocFormPrerender we replace the fully parsed Chunk with the note, the fully parsed Chunk, and the end note:

$note = $getNote($modx, $chunkName, $prefix);
$output = str_replace($search, $note . $search . $endNote, $output);

Then we unset the $_SESSION variable and the $search variable, so we’re ready to process the next Chunk tag.

The Switch Statement

Since we now have three events attached to the Plugin, we need a way to make sure that when one of the three events fires, only the code that’s appropriate for the event executed. We do that with PHP’s switch statement, which selects the code to execute based on $modx->event->name which contains the name of the event that has been called with $modx->invokeEvent().

A switch statement like this will work for any Plugin connected to more than one event. If a Plugin is only connected to one event (as we saw in the previous article), there’s no need for a switch statement, since there’s only one event that could possibly have fired—the one attached to the Plugin.

New Pattern

We’ve updated the regular expression pattern. Here’s the new one:

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

The new pattern automatically ignores any output modifiers or properties when capturing the Chunk name. The capture part now ([^\]:?]+). This captures any character that is not ], :, or ?. The backslash in this part is unnecessary, but I think it makes the regex slightly easier to read.

Because that parenthesized part of the pattern will stop before any colon or question mark, we have to add matches for them after the parentheses to make sure the full tag is captured for Chunks with output modifiers or properties in the tag. We do that by adding .*?]] after the parentheses. The dot matches any character. The * captures 0 or more of those characters up to the closing brackets, ]]. The question mark makes the match “non-greedy”. Without it the full tag match would continue to the very last ]] in the text being searched, so it could go well beyond the full Chunk tag.

The Code

Here’s the new Plugin code:

<?php
/**
 * ChunkInfo plugin for ChunkInfo extra
 *
 * Copyright 2023 Bob Ray <https://bobsguides.com>
 * Created on 12-15-2022
 *
 * ChunkInfo is free software; you can redistribute it and/or modify it under the
 * terms of the GNU General Public License as published by the Free Software
 * Foundation; either version 2 of the License, or (at your option) any later
 * version.
 *
 * ChunkInfo is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along with
 * ChunkInfo; if not, write to the Free Software Foundation, Inc., 59 Temple
 * Place, Suite 330, Boston, MA 02111-1307 USA
 *
 * @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
 **/

 /* Attach  plugin to OnWebPageInit, OnParseDocument,
    and OnWebPagePrerender.

   Create a Yes/No System setting 
   with the key: show_chunk_info
   to turn this on and off */

$showChunkInfo = $modx->getOption('show_chunkinfo', null, false, true);

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

$prefix = $modx->getVersionData()['version'] >= 3
    ? '\MODX\Revolution\\'
    : '';

$pattern = '/\[\[!*\$([^\]:?]+).*?]]/';
$endNote = '<span class="chunk_note">[End of chunk]</span>';

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

    /* Remove output modifiers, 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');
        }
    }

    $link = $chunkName;

    /* Uncomment to add a link to edit chunk in Manager.
       NOT RECOMMENDED because is exposes your Manager URL */

    /* $action = 'element/chunk/update&id=' . $chunkId;
    $link = '<a href="[[++manager_url]]?a=' . $action .
        '" target="_blank">' . $chunkName . '</a>'; */

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

switch ($modx->event->name) {

    /* Get tags from Template, only on
       first pass through OnParseDocument,
       and store in $_SESSION variable */
    case 'OnParseDocument':
        if (isset($_SESSION['chunk_matches'])) {
            break;
        }
        /* @var $content string */
        $success = preg_match_all($pattern, $content, $matches);

        if ($success) {
            $_SESSION['chunk_matches'] = $matches;
        }
        break;

    /* Get tags in Template from $_SESSION variable
       set by code above. Add note as prefix */
    case 'OnWebPagePrerender':
        $tags = $modx->getOption('chunk_matches', $_SESSION, array(), true);

        $output = &$modx->resource->_output; // get a reference to the output

        $i = count($tags[0]) - 1;
        while ($i >= 0) {
            $chunkName = $tags[1][$i];

            $chunk = $modx->getObject($prefix . 'modChunk', array('name' => $chunkName));

            /* Get the processed chunk */
            /** @var modElement $chunk */

            $content = $chunk->getContent();
            if (! $content) {
                $modx->log(modX::LOG_LEVEL_ERROR, '[getChunkInfoPlugin] No Content');
                break;
            }

            $parser = $modx->getParser();

            if (! $parser) {
                $modx->log(modX::LOG_LEVEL_ERROR, '[getChunkInfoPlugin] No Parser');
                break;
            }

            /* Define how deep we can go */
            $maxIterations = (integer)$modx->getOption('parser_max_iterations', null, 10);

            /* Parse cached tags, while leaving unprocessed tags in place */
            $parser->processElementTags('', $content, false, false, '[[', ']]', [], $maxIterations);

            /* Parse uncached tags and remove anything that could not be processed */
            $parser->processElementTags('', $content, true, true, '[[', ']]', [], $maxIterations);

            $search = $content;

            /* Call anonymous function to get note */
            $note = $getNote($modx, $chunkName, $prefix);

            /* Inject note; add endNote */
            $output = str_replace($search, $note . $search . $endNote, $output);

            $i--;
        }
        /* Clear the $_SESSION variable */
        unset($_SESSION['chunk_matches'], $chunk);
        break;

    /* Get tags in resource content field and wrap in note */
    case 'OnWebPageInit':
        $modx->regClientCSS(MODX_ASSETS_URL . 'components/chunkinfo/css/chunkinfo.css');

        $doc = $modx->getObject($prefix . 'modResource', $modx->resourceIdentifier);

        $modx->resource = $doc;

        $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];
                $catName = 'None';

                $chunk = $modx->getObject($prefix . 'modChunk',
                    array('name' => $chunkName));
                if ($chunk) {
                    $cat = $chunk->getOne('Category');
                    if ($cat) {
                        $catName = $cat->get('category');
                    }
                    $chunkId = $chunk->get('id');
                }

                $note = $getNote($modx, $chunkName, $prefix);
                $content = str_replace($fullTag, $note . $fullTag . $endNote, $content);
            }
            $modx->resource->setContent($content);
        }
        break;
}

return;

Warning

Here’s a repeat of the warning from my previous article:

IMPORTANT: The code of this Plugin won’t harm the Resources it processes, but it 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.

Improvements

The Plugin code above could be modified to display similar information for content brought in through Snippet tags, System Setting tags, language tags, TV tags, and/or link tags. It would mean adding code to all three parts of the switch statement, creating a new regular expressions that capture only one kind of MODX tag, and modifying the getNote function to identify the tag type. That’s all beyond the scope of this article, but feel free to implement it if you have the time and energy.

---

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.