A Jumplist with DirWalker in MODX

In the previous articles, we’ve been playing with producing a report based on the MODX codebase using the DirWalker class. Often, when you create a page that’s meant to be used as a reference, you want to put a “jumplist” at the top with links to the various parts of the document and insert links throughout the page that let the user jump back to the jumplist. No one wants to code that by hand and edit it each time the page changes.

In this article, we’ll look at how to create the jumplist and the “Back to Top” links automatically. We’ll add that to our previous code that reports on the MODX events in the core and manager directories. We’ll also make the output a tiny bit prettier. The new code is identified in comments.

The Code

As before, this code assumes that you’ve installed the DirWalker package or downloaded the class file. See the note below on where to get DirWalker. Like our previous example, it skips some types of files and directories and only looks in files with ‘.class’ in their names.

/* We override this method to process the files as found */
protected function processFile($dir, $fileName) {
/* Note that $dir is just the directory with no
trailing slash so we have to create the full path*/
$fullPath = $dir . ‘/’ . $fileName;

/* These are to make sure we’ve found them all */
$trueCount = 0;
$foundCount = 0;

/* *** New – Back to Top link at bottom of each section *** */
$output .= ‘<a style="font-size:10pt;" href="[[~[[*id]] ]]#top ">Back to Top</a>’;
}

return $output;
[/code]

The Output

You can see the output of the code above (which is much too long to post here) here. It reports all of the event invocations in the modx core and manager directories (excluding the few events that fire in add-on components), the files they occur in, and the arguments sent in each call to invokeEvent().

The Jumplist

The first bit of new code is an anchor link that goes at the top of the page:

[code language=”php”]
$output.= ‘<br/><a name="Top"></a>’;
[/code]

The link above is the target for all the “Back to Top” links we’ll insert at the end of each section of the report. Those links are produced by this line at the end of the code:

Next, we create the jumplist itself as a long string and add it to the output *after* the “Top” anchor link. Notice that the event name link is followed by a regular space followed by two non-breaking spaces. This insures some space between the entries but still lets the output wrap at the end of each line. Using all non-breaking spaces would put most of the jumplist off the right side of the page:

Finally, in the code loop that produces the main part of the report, we add a link target for each of the jumplist item links to jump to ($e is the event name):

[code language=”php”][/code]

$output .= ‘‘;

[code][/code]

One Drawback

Our code has one minor flaw. Because we’re using array_unique() on the jumplist, we only have one link to each event, so for events that occur in more than one file there will only be a link to the first instance. This can be solved, but the solution is complex and would slow down the page-load somewhat. Just removing the array_unique() call won’t help, because all the repeated links in the jumplist would still jump to the first instance. To solve it, we’d have add another member to the event array (or a prefix or suffix on the event name) in order to make each link in the jumplist and its target unique. Maybe that will be a topic for another blog article.

There are very few System Events that are called more than once, and for those, the variables sent are the same in every instance, so our flaw is quite minor, but still an annoyance.

Getting DirWalker

You can also install it in MODX through Package Manager (though the class does not require MODX) or get it at the MODX Repository. If you install the package, you’ll also get several files showing examples of how to use DirWalker to produce reports containing information gleaned from the MODX Codebase.