Wayfinder

From MODx Wiki

Wayfinder is a snippet 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.

Wayfinder 2.0 documentation can be found at http://www.muddydogpaws.com/development/wayfinder/features.html

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.

• Download the latest version of Wayfinder from the MODx repository.

Installation

MODx version 0.9.5 includes Wayfinder by default. To add Wayfinder to an older version of MODx or to upgrade to a newer version of Wayfinder:

• In the MODx Manager
  1. Create a new snippet.
  2. Name it Wayfinder.
  3. Copy the contents of snippet.wayfinder.tpl.php in to it.
• In the file system
  1. Create a new folder under /assets/snippets/.
  2. Name it wayfinder.
  3. Copy the file wayfinder.inc.php in to it.

Examples

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!]

Accordion menus with Wayfinder

• Accordion menu with Wayfinder
• Accordion menu with Wayfinder using JQuery

Parameters

General Parameters

&startId - (current docId)

the starting point for the menu (document ID)

&level - (0)

the depth to build the menu (0 goes through all levels)

&ignoreHidden - (FALSE)

ignore the show in menu checkbox for documents and include them in the menu

&ph - (FALSE)

name of a placeholder to set instead of directly returning the output results

&debug - (FALSE)

turn on debug mode for extra troubleshooting

&hideSubMenus - (FALSE)

set true to only output the active submenu

&removeNewLines - (FALSE)

set true to remove newline characters from output

&textOfLinks - (menutitle)

what database field do you want the actual link text to be? Use the following values: menutitle, id, pagetitle, description, parent, alias, longtitle, introtext

&titleOfLinks - (pagetitle)

what database field do you want the title of your links to be? Use the following values: menutitle, id, pagetitle, description, parent, alias, longtitle, introtext

&rowIdPrefix - (FALSE)

if set, creates a unique id for each item (id is value of rowIdPrefix + docId)

&useWeblinkUrl - (TRUE)

if set to TRUE the link specified in the weblink will be output to the placeholder [+wf.link+]

&excludeDocs - (0)

comma separated list of document IDs to exclude from the results

Template Parameters

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

&outerTpl

the template chunk for the outer most container

Placeholders

[+wf.classes+] - where classes specifed will be inserted (includes class=" ")

[+wf.classnames+] - outputs the just the class names (without class=" ")

[+wf.wrapper+] - where inner content will be inserted

Example

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

&rowTpl

the template chunk for the row items

Placeholders

[+wf.classes+] - where classes specifed will be inserted (includes class=" ")

[+wf.classnames+] - outputs just the class names (without class=" ")

[+wf.link+] - the href value for your link

[+wf.title+] - text for the link title

[+wf.linktext+] - text for the link display

[+wf.wrapper+] - where to insert a submenu

[+wf.id+] - where to insert a unique id

[+wf.attributes+] - where to insert link attributes

[+wf.docid+] - the document identifier for the current item

[+wf.description+] - the document's description

Example

<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>

&parentRowHereTpl

the template chunk for the current document if it is a container and has children

Placeholders

same as rowTpl

Example

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

&parentRowTpl

the template chunk for any document that is a container and has children

Placeholders

same as rowTpl

Example

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

&hereTpl

the template chunk for the current document

Placeholders

same as rowTpl

Example

<li[+wf.classes+]><span>[+wf.linktext+]</span>[+wf.wrapper+]</li>

&innerTpl

the template chunk for the any subfolders listed

Placeholders

same as outerTpl

Example

<ul[+wf.classes+]>[+wf.wrapper+]</ul>

&innerRowTpl

the template chunk for the row items in a subfolder

Placeholders

same as rowTpl

Example

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

&innerHereTpl

the template chunk for the current document if in a subfolder

Placeholders

same as rowTpl

Example

<li[+wf.classes+]><span>[+wf.linktext+]</span>[+wf.wrapper+]</li>

&activeParentRowTpl

the template chunk for the items that are containers, have children, and are currently active in the tree

Placeholders

same as rowTpl

Example

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

&categoryFoldersTpl

the template chunk for category folders, category folders are determined by setting the template to blank or by setting the link attributes field to rel="category"

Placeholders

same as rowTpl

Example

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

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.

&firstClass - ()

CSS class denoting the first item at a given menu level

&lastClass - (last)

CSS class denoting the last item at a given menu level

&hereClass - (active)

CSS class denoting the "you are here" state all the way up the chain

&selfClass - ()

CSS class denoting the "you are here" state for current doc only

&parentClass - (parent)

CSS class denoting the menu item is a container and has children

&rowClass - ()

CSS class denoting each output row

&levelClass - ()

CSS class denoting each output rows level, the level number will be added to the specified class (i.e. level1, level2, level3, etc...)

&outerClass - ()

CSS class for the outer template

&innerClass - ()

CSS class for the inner template

&webLinkClass - ()

CSS class for weblinks

Example To add one of these parameters to the snippet call use this format: &levelClass=`level`

This 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.

&cssTpl - (FALSE)

name of a chunk containing css you would like added to the page

&jsTpl - (FALSE)

name of a chunk containing javascript you would like added to the page