How Wayfinder Templates Work
Wayfinder constructs its output based upon a set of templates, each of which determines how a portion of the generated output should be constructed.
Basically, each template is an HTML fragment with some embedded MODx placeholders. The HTML provides the static, fixed structural portion of Wayfinder's output (the parts that will remain the same on each page where Wayfinder is called), while the placeholders provide the dynamically-generated content (the parts that will be different for each page, and that reflect each page's unique properties).
Also note that you can call Wayfinder multiple times on the same page, and each call can use an entirely different set of templates. This allows you a lot of flexibility in creating main menus, side menus, quick reference lists, or whatever else you might like to do that is in some way derived from a list of documents in the MODx document tree.
The overall schema whereby the templates are joined together is as shown below.
If (and only if) the &displayStart parameter is TRUE, then the &startItemTpl template will be used. When it's used, the &outerTpl template will be placed in the former's [+wf.wrapper+] placeholder.
If the &displayStart parameter is not TRUE, then the &startItemTpl template is not used, and the &outerTpl template provides the outermost container for Wayfinder's output.
The &startItemTpl template will be used at most once in the Wayfinder output.
The &outerTpl template is one of only two always-required templates (and for which a default template is built into Wayfinder). All the rows that comprise the menu's items are placed within this template's [+wf.wrapper+] placeholder.
The &outerTpl template will always be used at least once in the Wayfinder output, as the "container" of the highest level of the menu hierarchy. And if no &innerTpl template is specified, then it will also be used as the container for every sub-menu in the generated output.
For each document that Wayfinder needs to list in the generated output, a "row" is generated. By default the &rowTpl template is used to construct these rows.
This template should include a [+wf.wrapper+] placeholder, because that's where Wayfinder will place any sub-menu that needs to appear beneath any given row.
<a href="[+wf.link+]" title="[+wf.title+]" [+wf.attributes+]>[+wf.linktext+]</a>
There are a variety of row-level templates that can be used to produce different row output under different conditions. Each of these that you choose to specifiy will be used instead of the generic &rowTpl template when a document meets certain criteria, e.g.: has children (&parentTpl), is the document whose web page is currently being displayed (&selfTpl), does not have a web page template (&categoryFoldersTpl), etc.
If the &innerTpl template is defined, then it will be used as the "container" for all the sub-menus, no matter how deeply nested, that Wayfinder outputs. It is within this template's [+wf.wrapper+] placeholder that all the rows for a sub-menu are placed.
If an &innerTpl template is not defined, then the &outerTpl template will be used in its place.
This is the generic row-generation template for all rows that appear within an &innerTpl template. If this template is not defined, then the &rowTpl template will be used instead. [but what happens if the &innerTpl is not defined? will the &innerRowTpl still be used for sub-menus?]
Other Row-Level Templates
All the templates not mentioned above are row-level templates that are used in place of the generic &rowTpl and &innerRowTpl templates, depending on the properties of each document.
But what's not clear at this point is: (a) Do all of these work within sub-menus, or only within the top-level menu? (b) What happens if the &innerTpl template is not defined -- do these alternative, row-level templates still take effect within sub-menus?