Wayfinder

From MODx Wiki
Jump to: navigation, search
Wayfinder Logo

 MODx Snippet 

Wayfinder v1.0.1
Author 
kylej
MODx Versions 
>= 0.9.2.1
Last Updated 
11/7/2006

Contents

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

The actual Wayfinder 2.0 wiki can be found at http://wiki.modxcms.com/index.php/Wayfinder200

For Wayfinder discussions on the MODx forums see http://modxcms.com/forums/index.php/board,182.0.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.

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

Parameters

General Parameters

&startId

Default: current docId
the starting point for the menu (document ID)

&displayStart

Default: FALSE
show startID item in menu

&level

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

&ignoreHidden

Default: FALSE
ignore the show in menu checkbox for documents and include them in the menu

&ph

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

&debug

Default: FALSE
turn on debug mode for extra troubleshooting

&hideSubMenus

Default: FALSE
set true to only output the active submenu

&removeNewLines

Default: FALSE
set true to remove newline characters from output

&textOfLinks

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

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

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

&useWeblinkUrl

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

&excludeDocs

Default: 0
comma separated list of document IDs to exclude from the results

&fullLink

Default: FALSE
Used for deciding whether or not to use absolute URLs. Set to TRUE to use absolute URLs.

&sortBy

Default: menuindex
Use for sort row (id | menutitle | pagetitle | introtext | menuindex | pub_date | published | hidemenu | parent | isfolder | description | alias | longtitle | type | template)

&sortOrder

Default: ASC
Used for sort row (ASC | DESC)

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>

&startItemTpl

the template chunk for start item, if shown using the &displayStart parameter
Placeholders
same as rowTpl
Example
<h2 class="menustart"><a href="[+wf.link+]">[+wf.linktext+]</a></h2>[+wf.wrapper+]
Note that the default template shows the start item but does not link it. If you do not need a link, a class can be applied to the default template using the parameter &firstClass=`className`

&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

Default:
CSS class denoting the first item at a given menu level

&lastClass

Default: last
CSS class denoting the last item at a given menu level

&hereClass

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

&selfClass

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

&parentClass

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

&rowClass

Default:
CSS class denoting each output row

&levelClass

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

&outerClass

Default:
CSS class for the outer template

&innerClass

Default:
CSS class for the inner template

&webLinkClass

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

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

&jsTpl

Default: FALSE
name of a chunk containing javascript you would like added to the page
Personal tools