Part Three - Add-Ons

Menus

Menus and lists based on selecting specified resources is probably something that every site will need in one form or anther. There are quite a lot of add-ons to build and organize such lists, most commonly Wayfinder for nested menus and getResources for aggregated lists, with getPage often being used as a wrapper for these snippets to provide prev/next style paging of their resulting lists

These listing snippets provide various options, or properties, and many are little-known and seldom used. But they can modify the behavior of the snippet in many ways, and along with the use of Output Modifiers, other snippets and MODX tags generate just about any kind of list you could ever imagine.

One of the more common uses of listing snippets like getResources or getImageList (if the list is coming from a MIGx TV) is to provide the input for a Javascript slider, tabs or an accordion. Using the properties and tpls (mini-templates) for the snippet can generate exactly the HTML structure any given Javascript app requires.

The same versatility goes for Wayfinder in generating the various structures needed for Javascript-driven menus as well. While all by itself Wayfinder generates a simple nested unordered list with a couple of default classnames that can be used out-of-the-box for most menus, it can be configured with its properties to generate any HTML code that any fancy menu expects.

While many of the properties of these snippets involve selecting which resources to display, the heart of the whole process lies in the infinitely customisable tpls they use to structure their output. Generally these mini-templates (called 'tpls' to avoid confusion with the main site Templates) are chunks, but can also be defined inline in the snippet's properties or as files, if the snippet is written to allow it. These tpls are applied to each resource in turn as the snippet processes them. This leads to a crucial point that must be understood about these snippets and their tpls - placeholders.

Placeholders

Perhaps the best way to explain placeholders is to use an example. Let's say we're generating a very basic "Latest News" list for our sidebar, displaying a heading, a brief summary and a link to a few of the latest News resources. Usually for such a list we'll use getResources, since that's exactly what it was written to do.

  [[getResources? &parents=`3` &limit=`4` &tpl=`latestNewsTpl`]]

We're telling the getResources snippet to get 4 resources that are children of resource #3 in our Resource Tree, and use a chunk named 'latestNewsTpl' to structure each item.

  <article class="latest-news">
    <a href="[[~[[+id]]]]"<h3>[[+pagetitle]]</h3></a>
    <p>[[+introtext]]</p>
    <a href="[[~[[+id]]]]">Read more...</a>
  </article>

Notice here that we have used three of the basic Resource Variables, pagetitle, id and introtext. But instead of using the [[*... tags that we would normally use to display these values for a resource, we've used [[+... placeholder tags.

The [[*... tags would refer to those values for the current page... the actual resource that the visitor is looking at, the page containing our getResources snippet call. If our user is seeing our Latest News sidebar listing on the home page, resource #1, all four items in the list would have the pagetitle, id and introtext for resource #1. Not at all what we had in mind!

When a listing snippet like Wayfinder or getResources that uses tpls initially fetches items to work with, it stores some of each resource's values by default. You can usually customise which values it fetches in the snippet properties. When it processes the items, for each item it applies those values to the tpl you specified; in our getResources case the latestNewsTpl chunk. Each placeholder tag gets replaced with the values for that resource in the list. Any other MODX tags in the tpl are handled by MODX as they usually are. Then, in the case of a list like ours, getResources moves on to the next item in its list and does the same thing to that one. So each resource in the list will get the values for that resource, and not for the resource that the visitor is currently viewing.

• Menu Item Opens Its First Child