Configuration Files

Introduction

Wayfinder allows you to package into a single configuration file all of the specifications that you would otherwise have to make through a series of parameters, chunks (for the templates) and external files (for CSS or JavaScript). This way you can call Wayfinder with just a single &config parameter, and get a complete set of specifications for the call.

In a given configuration file you can specify as many or few of the parameters, templates and external files as you wish. Then in a Wayfinder call (in addition to specifying the configuration file with the &config parameter) you have the option of including additional parameters that add to or override the values specified in the configuration file. [Did I guess right about this?]

Naming and Placing the Configuration File

The configuration file is required to have a name in the format <name>.config.php, where <name> is what you specify in the Wayfinder call (e.g.. if the filename is "mainmenu.config.php", the Wayfinder call would be [!wayfinder! &config=`mainmenu`!].

The configuration file must be placed in the directory ... /assets/snippets/wayfinder/configs/.

Internal Syntax

The configuration file is essentially as PHP script that runs in the context of the Wayfinder call. It primarily consists of statements that assign values to Wayfinder internal variables -- which have the same names as the Wayfinder snippet parameters (except that within the configuration file you precede each variable name with a dollar sign ($), whereas in a snipppet call you precede each variable name with an ampersand (@).

In other words, the contents of a configuration file is typically structured thus:

<?php
 $<parameter name> = <value> ;
 $<parameter name> = <value> ;
 $<parameter name> = <value> ;
 $<parameter name> = <value> ;
 $<parameter name> = <value> ;
?>

In addition, different value types have slightly different requirements, as follows:

Integer values don't require any special punctuation. E.g.:

<?php
 $startID = 0 ;
 $level = 1 ;
?>

Text values must be quoted [with single-quotes?]. E.g.:

<?php
 $sortBy = 'pagetitle' ;
 $sortOrder = 'DESC' ;
 $outerClass = 'menu' ;
 $rowTpl = 'theNameOfTheChunkWithTheRowTemplate' ;
?>

Embedded templates must both be quoted [with single-quotes?] and must begin with "@CODE:". E.g.:

<?php
 $outerTpl = '@CODE:<div[+wf.classes+]> <ul> [+wf.wrapper+] </ul> </div>';
?>

Notice that even though the parameter value in the above example takes up multiple lines, it still is enclosed in quotes and terminated with a semicolon.

The &cssTpl parameter normally specifies an external CSS file. But within the configuration file you simply include the content of the style sheet, wrapped in an HTML "style" element, just as if you were typing the stylesheet directly into the HEAD of a web page. E.g.:

<?php
 $cssTpl = '@CODE:<style type="text/css">
 /*CSS stylesheet comments may be included if desired*/
 #nav, #nav ul {padding: 0;margin: 0;list-style: none}
 #nav a:hover {color:#000}
 </style>';
?>

I imagine that the &jsTpl parameter is handled in a similar way...???

Any PHP Code is Legal for Inclusion???

The example "breadcrumb" configuration file that ships with Wayfinder 2.0 has some funny stuff in it. It looks like some PHP is being used to set the value of a variable $homelink, and then $homelink is being called from within the template with {$homeLink}. This brings up some questions:

Is this curly-bracket notation a MODx standard that can be used elsewhere, or does it only work in a Wayfinder config file?
Are we able to embed any PHP we want, and does it then execute within the Wayfinder context?
If so, then I assume we have to be careful not to create any variables with the same names as those used internally within Wayfinder?

Here's the "breadcrumb" example file:

<?php
 $hideSubMenus = 1;

 if ($modx->config['site_start'] == $modx->documentObject['id'])
 {
 $homeLink = '';
 }
 else
 {
  $homeLink = "<a href=\"{$modx->config['site_url']}\" title=\"home\">Home</a> &raquo; ";
 }
 $outerTpl = "@CODE:<div id=\"breadcrumbnav\"> {$homeLink}[+wf.wrapper+] </div>";
 $innerTpl = '@CODE:[+wf.wrapper+]'; $rowTpl = '@CODE: ';
 $activeParentRowTpl = '@CODE:<a href="[+wf.link+]" title="[+wf.title+]">[+wf.linktext+]</a> &raquo; [+wf.wrapper+]';
 $hereTpl = '@CODE:[+wf.linktext+]';
?>

Open Questions

If you define CSS or JavaScript in a config file, what gets put in the HEAD section of the generated page? There's no file to link to, so does it just bulk copy the CSS or JavaScript into the HEAD section of the generated page?