Wayfinder

Wayfinder is a Snippet by kylej that scans a specified portion of the MODX document tree, finds all documents that satisfy a certain criteria (determined by the Parameters), and outputs a formatted list of those documents. The formatting of the output is template-driven, and can contain any combination of HTML, CSS and JavaScript, yielding an enormous degree of flexibility.

Wayfinder's primary purpose is to generate navigational menus that automatically update to reflect changes made to the document tree, but it can be used for other purposes as well.

Since you can make multiple calls to Wayfinder on a single page, and each call can specify a different section of the document tree, you can have multiple navigational menus or document lists on a single page. For example you may wish to have a main menu at the top of the page, then along the sides have secondary menus for products, services, teams, roles, etc. Each pertaining to a different section of the document tree.

Please note that since the release of Revolution there are two types of Wayfinder snippets available, one for each version. For clarity, this page uses the Evolution syntax when showing examples. Generally speaking the functionality between the two versions are the same, and so are the parameters. Mind that in Revolution, snippets must be called with [[Wayfinder? &...]] instead of [!Wayfinder? &...!].

For Wayfinder discussions on the MODX forums see https://forums.modx.com/index.php/board,182.0.html.

In case you want to read everything about Wayfinder, there's a 148 page ebook written by Kongondo to be found on the forum which covers all aspects about Wayfinder. Read about it here.

History¶

Wayfinder has been totally re-factored from the original DropMenu navigation builder to make it easier to create custom navigation by using Chunks as output templates. By using templates, many of the parameters are no longer needed for flexible output including tables, unordered- or ordered-lists (ULs or OLs), definition lists (DLs) or in any other format you desire.

Version history¶

Installation¶

Downloads¶

• Download the latest version of Wayfinder for Revolution from the MODX Extras Repository, or install via Package Management.
• Download version 2.0 for Evolution from MuddyDogPaws.

Evolution (and before)¶

MODX version 0.9.5-1.0 includes Wayfinder by default in the installer. To add Wayfinder to an older version of MODX or to upgrade to a newer version of Wayfinder in Evolution:

1. Download the neccesary files from the link above.
2. Create a new snippet in your MODX Manager (Elements -> Manage Elements -> Snippets) and name if Wayfinder.
3. Copy the contents of snippet.wayfinder.tpl.php to the snippet contents.
4. Create a new folder in your file system under /assets/snippets/ and call it wayfinder.
5. Copy the file wayfinder.inc.php to the new folder.

Revolution¶

In MODX Revolution, Wayfinder can be downloaded via Package Management. Simply load Package Management, click "Download Extras", go to Navigation -> Wayfinder and download the latest version. Then right click in your Packages grid, and click Install. After it installs, you're finished and good to go.

Getting started¶

The minimum Wayfinder snippet call:

[[Wayfinder? &startId=`0`&level=`1`]]

will output the HTML for a multi-level, unordered list of the entire document tree (with certain exceptions), where each list item is a link to a corresponding document in the MODX document tree.

See Wayfinder Introductory Examples for some thorough examples comparing Wayfinder snippet calls to HTML output.

Parameters¶

General Parameters¶

Template Parameters¶

These parameters specify the chunks that contain the templates that will drive the generation of Wayfinder's output.

With the current version of WayFinder in Revolution, you can access your own custom TVs by using a placeholder without the 'wf.' prefix, e.g. [[+my\_TV]]

As of this writing, only the raw TV value will be returned: it will not be formatted. E.g. if your TV is an image, normal use of the TV inside your template would return the full image tag, but inside of a WayFinder tpl, only the path to the image will be returned.

If you want MODX 2.x to process a TV (e.g. an image TV with a base path/url as an input option (since MODX 2.1.x) or with an @inherit value) you might do that by calling a snippet within the wayfinder row template (&rowTpl). Let's say, your image TV is named icon. Normally you would use some code thing like this:

... <img src="[[+icon]]" /> ...

But it will not get you the fully processes TV. Just change your code to this:

... <img src="[[processTV? &myId=`[[+id]]` &myTV=`icon` ]]" /> ...

Within the snippet processTV you place this php-code:

<?php
$doc = $modx->getObject('modResource', $myId);
return $doc->getTVValue($myTV);

As a result the full processed image TV is returned.

&outerTpl¶

Name of the chunk containing the template for the outer most container; if not included, a string including [[+wf.wrapper]] is assumed

Available placeholders are:

• wf.classes - outputs relevant classes (including class=" ")
• wf.classnames - outputs relevant classes (without class=" ")
• wf.wrapper - outputs inner (row) contents. This placeholder is required.

Please note that you will need to wrap the placeholders with the relevant tags.

Evolution: [+wf._____+]
Revolution: [[+wf._____]]

Example of an &outerTpl chunk (Evo):

<ul id="topnav"[+wf.classes+]>[+wf.wrapper+]</ul>

Revo:

<ul id="topnav"[[+wf.classes]]>[[+wf.wrapper]]</ul>

The following table shows other parameters to change your output, that use the same placeholders as the &outerTpl parameter.

&rowTpl¶

Name of the chunk containing the template for the regular row items. Available placeholders are:

• wf.classes - outputs relevant classes (including class=" ")
• wf.classnames - outputs relevant classes (without class=" ")
• wf.link - the href value for your link
• wf.title - the title text for the link, from the field as specified in the &titleOfLinks parameter
• wf.linktext - the text for the actual link, from the field as specified in the &textOfLinks parameter
• wf.wrapper - outputs inner contents such as submenus
• wf.id - outputs a unique ID attribute. You will need to specify the &rowIdPrefix parameter in order for this placeholder to receive a value. The value is your prefix + the docId.
• wf.attributes - outputs the link attributes of the current item
• wf.docid - the document identifier for the current item
• wf.description - the current item's description
• wf.level - the current depth of item (added in v2.3.3)

Please note that you will need to wrap the placeholders with the relevant tags.

Evolution: [+wf._____+]
Revolution: [[+wf._____]]

Since version 2.3.0 you can use placeholders for all fields of a Resource, such as [[+introtext]], [[+menutitle]], [[+published]], etc. Since version 2.3.2 placeholder [[+protected]] is added that is 1 if Resource is protected by a Resource Group.

Examples of a &rowTpl (or related) chunk:

<li[+wf.id+][+wf.classes+]><a href="[+wf.link+]" title="[+wf.title+]" [+wf.attributes+]>[+wf.linktext+]</a>[+wf.wrapper+]</li>

<li><a href="[+wf.link+]">[+wf.linktext+]</a> - [+wf.description+]  [+wf.wrapper+]</li>

Revo:

<li[[+wf.id]][[+wf.classes]]><a href="[[+wf.link]]" title="[[+wf.title]]" [[+wf.attributes]]>[[+wf.linktext]]</a>[[+wf.wrapper]]</li>

<li><a href="[[+wf.link]]">[[+wf.linktext]]</a> - [[+wf.description]]  [[+wf.wrapper]]</li>

The following table shows other parameters to change your output, that use the same placeholders as the &rowTpl parameter.

&parentRow and &activeParentRow require that the parent resource's "Container" setting is checked.

Example of how &startItemTpl could be used:

<h2 class="menustart"><a href="[+wf.link+]">[+wf.linktext+]</a></h2>[+wf.wrapper+]

CSS Class Name Parameters¶

You can use CSS to control the appearance (and in some cases the behavior) of various portions of the generated output. But it's up to you to tell Wayfinder the CSS classnames you want to use, and which portions of the generated output you want them associated with.

Example:

Simply specify the class parameters in the snippet to add the classnames to the output.

For example, adding &levelClass=level will result in

<li class="level2">

Code-Embedding Parameters¶

If the generated output of a Wayfinder call requires the presence of certain CSS or JavaScript, you can store the CSS in one chunk and the JavaScript in another, then use these parameters to have Wayfinder copy one or both chunks into the HEAD section of the webpage in which the Wayfinder call is made.

Default values in Revolution¶

Examples¶

See Wayfinder Introductory Examples for some thorough examples comparing Wayfinder snippet calls to HTML output.

The Minimum Wayfinder Call¶

The snippet call:

[[Wayfinder? &startId=`0`]]

will output the HTML for a multi-level, unordered list of the entire document tree (with certain exceptions), where each list item is a link to a corresponding document in the ModX document tree.

Replacing DropMenu with Wayfinder¶

Some older templates may use the deprecated DropMenu snippet instead of WayFinder. The DropMenu snippet is not included in MODX 0.9.5 or above. These templates can often be easily updated to use Wayfinder by replacing the call to DropMenu as follows:

Example DropMenu call in template file:

[[DropMenu?startDoc=`0`&levelLimit=`1` ]]

Can be replaced by

[[Wayfinder? &startId=`0`&level=`1`]]