Wayfinder200

From MODx Wiki

[Note that within this document italicized text, particularly within square brackets, indicates unanswered questions or unverified guesses.]

For a zipped HTML file that attempts to exhaustively document Wayfinder 2.0, click here media:Wayfinder200_docs_v6.zip

Description

Wayfinder 2.0 is a MODx snippet, whose primary purpose is to generate navigational menus that automatically update to reflect changes made in the MODx document tree.

Each time Wayfinder is called, it scans a specified portion of the MODx document tree, finds all documents that satisfy specified conditions, and outputs a formatted listing of those documents.

The formatting of the output is template-driven, and can contain combinations of HTML, CSS and JavaScript, yielding an enormous degree of flexibility. Thus you have great control over the content, appearance and behavior of the generated output.

Since you can make multiple calls to Wayfinder on a single page, and since 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 sub-menus for products, services, teams, roles, etc. -- each listing documents from a different portion of the document tree. You may additionally want a breadcrumb trail. All of these can co-exist on the same page.

History

Up until MODx 0.9.2, a snippet named DropMenu was used to create navigational menus. Then, in about October 2006, Kyle Jaebker created Wayfinder as a more flexible and capable replacement for DropMenu. Wayfinder was refactored 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 DropMenu parameters were no longer needed, yet the range of output became more flexible. Wayfinder can output hierarchical, ordered or unordered lists, complex table structures, definition lists (DLs) or any other HTML structure you might desire -- along with any associated CSS and JavaScript that you provide. Starting in MODx 0.9.5 Wayfinder is officially included in the MODx installation, and DropMenu is officially deprecated.

Release History

v1.0, 23oct06, by Kyle Jaebker, works with MODx v0.9.2.1

v1.0.1, 7nov06, by Kyle Jaebker, works with MODx: 0.9.5, 0.9.2.2, 0.9.2.1

v1.0.2, date?, by Kyle Jaebker

v2.0, 27feb07, by Kyle Jaebker, works with MODx: 0.9.5 and...?

Installation

Wayfinder 1.0 is included with MODx 0.9.5. To upgrade to a newer version of Wayfinder, or to install Wayfinder in an earlier version of MODx:

1. In the MODx Manager:
   1. create a new snippet
   2. name it Wayfinder (note capital "W")
   3. and copy into it the contents of the file snippet.wayfinder.tpl.php
2. In the file system:
   1. create a new folder under ... /assets/snippets/
   2. name it wayfinder (note lowercase "w")
   3. and copy into it the file wayfinder.inc.php

If installing in a MODx version earlier than 0.9.5 [???], note that &cssTpl and &jsTpl parameters use regClientCSS or regClientStartupScript. These may not work correctly unless you have patched the parser with this: http://modxcms.com/forums/index.php/topic,1942.msg18783.html#msg18783

Documentation Notes

In the documentation downloadable from the link at the top of the page, the question is asked in reference to two different types of placeholders:

Have the following placeholders been eliminated in Wayfinder 2.0, because you can now reference these standard document fields without the "wf." prefix, or have they been retained for backwards compatibility???

The answer is NO!

These two forms will insert two entirely different things. The standard document fields will insert the specified field taken from the document being viewed. The wf. prefix will insert the field taken from the document the link is being generated for. So if you used a placeholder without the wf. prefix in a row-level template chunk, all of the rows using that template would have the same value, taken from the page that is being viewed.