1. Evo Documentation
      1. Administration
        1. Admin Users
          1. Admin Roles And Groups
          2. Reset your Password - Unblock your User
          3. Why Admin Users, Roles and Groups
        2. Friendly URL Solutions
        3. Moving Site
        4. Taking sites down for maintenance
        5. Upgrading
        6. Web Users
          1. Creating a Web User
          2. Web User Groups and Document Groups
          3. Why Web Users and Groups
      2. Content Editing
        1. Editing Resources
          1. Creating a Resource
          2. Edit a Resource
          3. Move a Resource
          4. Publishing a Resource
          5. Select a Template
        2. Evo Tags
          1. Document Variables
        3. Terminology
        4. The Admin Interface
        5. Who Should Read This
      3. Designing
        1. Adding Chunks
        2. Adding Snippets
        3. Adding Tags
          1. Resource Fields
        4. Cross References
        5. Document Caching
        6. Modifiers
          1. @ Modifiers
        7. Template Basics
      4. Developer's Guide
        1. API Reference
          1. DBAPI
            1. delete
            2. escape
            3. getInsertId
            4. query
            5. select
            6. update
          2. Document Object
          3. DocumentParser Object
            1. addEventListener
            2. changeWebUserPassword
            3. documentContent
            4. documentGenerated
            5. documentIdentifier
            6. documentListing
            7. documentMethod
            8. documentObject
            9. evalSnippet
            10. getAllChildren
            11. getCachePath
            12. getChildIds
            13. getDocumentChildren
            14. getDocumentChildrenTVarOutput
            15. getDocumentChildrenTVars
            16. getLoginUserID
            17. getLoginUserName
            18. getLoginUserType
            19. getManagerPath
            20. getParent
            21. getParentIds
            22. getUserData
            23. hasPermission
            24. isBackend
            25. isFrontend
            26. logEvent
            27. maxParserPasses
            28. minParserPasses
            29. regClientCSS
            30. runSnippet
            31. table_prefix
            32. tstart
            33. webAlert
        2. Chunks
        3. Modules
          1. How to create and run a module from within the Admin Interface
          2. Managing module dependencies
          3. Setting up configuration parameters
          4. Writing the module code
        4. Plugins
        5. Snippets
        6. Template Variables
          1. @ Bindings
            1. (at)CHUNK
            2. (at)DIRECTORY
            3. (at)DOCUMENT
            4. (at)EVAL
            5. (at)FILE
            6. (at)INHERIT
            7. (at)SELECT
            8. What are (at) Bindings
          2. Creating a Template Variable
          3. What are Template Variables
          4. Widgets
            1. DataGrid Widget
            2. Floater Widget
            3. Hyperlink Widget
            4. Marquee Widget
            5. Misc. Widget
            6. RichTextBox Widget
            7. Ticker Widget
            8. Viewport Widget
            9. What are Widgets
      5. Getting Started
        1. About Evo
        2. Basic Installation
    2. Evo Extras
      1. AjaxSearch
      2. AnythingRating
      3. Breadcrumbs
      4. directResize
      5. Ditto
        1. Examples
        2. Extenders
        3. Parameters
        4. Placeholders
      6. DocLister
        1. Examples
        2. Filters
        3. Main Parameters
        4. Notes for Developers
        5. Output Parameters
        6. Processing Before Output
      7. Easy 2 Gallery
      8. eForm
      9. EvoGallery
      10. FirstChildRedirect
      11. Jot
      12. MaxiGallery
      13. multiTV
        1. Examples
        2. Extras
        3. Installation
        4. Module
        5. Snippet
        6. Template Variable
      14. PHx
        1. Custom Modifiers
      15. Quill
      16. tagLinks
      17. TinyMCE
      18. TvTagCloud
      19. Wayfinder
        1. Examples
      20. Weblogin
      21. WebLoginPE
        1. API
        2. Parameters
        3. Placeholders
        4. Typical Errors
        5. Views (Templates)
        6. Working with Forms
      22. YAMS
        1. Configuration
        2. How To
          1. YAMS + Breadcrumbs
          2. YAMS + Ditto
          3. YAMS + Ditto + PHx
          4. YAMS + eForm
          5. YAMS + Jot
          6. YAMS + Snippets
          7. YAMS + Wayfinder
          8. YAMS Custom Multilingual TVs, Chunks, Snippets
          9. YAMS Language Dependent Layout
          10. YAMS Language Flag List
          11. YAMS Language Select Landing Page
          12. YAMS Mime-type Dependent Alias Suffixes
          13. YAMS Multilingual Weblinks
          14. YAMS XML Sitemap
        3. Installation
        4. Language Modes
        5. Language Settings
        6. Placeholders
        7. Setup
        8. Snippet
        9. Technical Details
    3. Evo Tutorials
      1. Extras - How To
        1. Ditto Tutorials
          1. Add Ditto Pagination
          2. Basic RSS feed
          3. Category Tagging with Ditto
          4. Create a Custom Ditto Template
          5. Custom Placeholders
          6. Dropdown Menu with Ditto
          7. Dynamically Show Related Posts
          8. Promote to Home Page
          9. Sort by a date tv
          10. Tagged blogging with Ditto (ex.1)
          11. Tagged blogging with Ditto (ex.2)
          12. Tagging Screencast

Wayfinder

This is a user-contributed Extra. If you find issues or would like more info or help, please contact the author.

Introduction

Wayfinder is a Snippet by kylej that scans a specified portion of the Evo 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.

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.

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

Evo (and before)

Evo version 0.9.5 - 1.x includes Wayfinder by default in the installer. To add Wayfinder to an older version of Evo or to upgrade to a newer version of Wayfinder in Evo:

  1. Download the necessary files.
  2. Create a new snippet in your Evo admin interface (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.

Parameters

General Parameters

Parameter Description Default
&startId The starting point (document ID) for the menu to list documents from. Specify 0 to start from the site root. current docId
&displayStart Show the document as referenced by &startId in the menu. FALSE
&level Depth (number of levels) to build the menu from. '0' goes through all levels. 0
&ignoreHidden Ignore the "Show in menu" checkbox for documents, and include them in the menu anyway. FALSE
&ph Name of a placeholder to set with the output results, instead of directly returning the output. FALSE
&debug Set to 'TRUE' to enable debug mode for extra troubleshooting. FALSE
&hideSubMenus Set to 'TRUE' to only output the active submenu. FALSE
&removeNewLines Set to 'TRUE' to remove newline characters from the output. FALSE
&textOfLinks The field to get the actual link text from. Possible values: menutitle, id, pagetitle, description, parent, alias, longtitle, introtext menutitle
&titleOfLinks The field to get the link title from. Possible values: menutitle, id, pagetitle, description, parent, alias, longtitle, introtext pagetitle
&rowIdPrefix If set, this parameter creates a unique ID for each item. The value will be rowIdPrefix + docId. FALSE
&useWeblinkUrl When set to TRUE, the link specified in a weblink document will be output to the placeholder [wf.link] instead of the link to the weblink. TRUE
&excludeDocs Comma seperated list of document IDs to be excluded from the menu. 0

Template Parameters

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

&outerTpl

Name of the chunk containing the template for the outer most container; if not included, a string including "<ul>[+wf.wrapper+]</ul>" 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.

[+wf._____+]

Example of an &outerTpl chunk:

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

Parameter Description
&innerTpl Name of the chunk containing the template for any subfolders listed in the menu.

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

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

[+wf._____+]

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>

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

Parameter Description
&startItemTpl Name of the chunk containing the template for the start item, if enabled via the &displayStart parameter. Note: 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 Name of the chunk containing the template for the current document if it is a container and has children. Remember the [wf.wrapper] placeholder to output the children documents.
&parentRowTpl Name of the chunk containing the template for any document that is a container and has children. Remember the [wf.wrapper] placeholder to output the children documents.
&hereTpl Name of the chunk containing the template for the current document.
&innerRowTpl Name of the chunk containing the template for the row items in a subfolder.
&innerHereTpl Name of the chunk containing the template for the current document if it is in a subfolder.
&activeParentRowTpl Name of the chunk containing the template for items that are containers, have children and are currently active in the tree.
&categoryFoldersTpl Name of the chunk containing the template for category folders. Category folders are determined by setting the template to blank or by setting the link attributes field to rel="category".

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.

Parameter Description Default
&firstClass CSS class for the first item at a given menu level.
&lastClass CSS class for the last item at a given menu level. last
&hereClass CSS class for the items showing where you are, all the way up the chain. active
&selfClass CSS class for the current item.
&parentClass CSS class for menu items that are a container and have children. parent
&rowClass CSS class denoting each output row
&levelClass CSS class denoting every output row level. The level number will be added to the specified class (level1, level2, level3 etc if you specified 'level').
&outerClass CSS class for the outer template.
&innerClass CSS class for the inner template
&webLinkClass CSS class for weblink items.

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.

Parameter Description
&cssTpl Name of a chunk containing the CSS you would like added to the page when the Wayfinder call is present.
&jsTpl Name of a chunk containing the JavaScript you would like added to the page when the Wayfinder call is present.

Template Variables

With the current version of WayFinder, 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.

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

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

 

In This Section

Suggest an edit to this page.