Bob's Guides

SiteAtoZ Snippet Tutorial

If you use this extra and like it, please consider donating. The suggested donation for this extra is $5.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-premium extras with a clear conscience.

The SiteAtoZ snippet for MODX Revolution makes use of getResources to list resources alphabetically, with an A to Z header of links to anchors in the text. Each section provides a sorted series of links to the selected resources. The snippet was inspired by the work of garryn, patricksamshire, and OpenGeek, but has been rewritten from scratch by Bob Ray for MODX Revolution 2 and MODX Revolution 3.

The SiteAToZ snippet assumes that every entry on the list is a separate resource, so this snippet will not work for you if you only have one page of items, and you want to create A to Z links for them.

Features

• Create A to Z jump links to selected documents
• Tpl chunk for formatting each item in the list
• (Optional) Use JavaScript to show only the section that's clicked on
• Context awareness
• Handles non-English alphabets
• Select resources by any field
• Sort resources by any field
• Include numbers 0-9 for resources with numeric pagetitles
• Combine numbers 0-9 into a single category
• Almost all getResources properties can be used to control selection and sorting
• Use a TV rather than the pagetitle for the title of entries

Making it Work

By far the best practice to get this snippet working is to start with getResources alone. Install both getResources and SiteAtoZ.

Create a new Resource called AtoZDemo and paste the following getResources tag in the Resource Contend section:

[[!getResources? &parents=`0` &tpl=`AzItemTpl`]]

If you installed siteAtoZ through Package Manager, you should already have the AzItemTpl chunk. If not, you can paste the code below into a chunk with that name.

<div class = "az-item">
<p>[[+pagetitle]] - [[+introtext] . . . <a href="[[~[[+id]]]]">See More</a></p>
</div>

Preview the AtoZDemo resource to see what resources it is selecting. You should see a list of all the resources on your site that are not published and not hidden from menus. Using the properties described here, set things up so that getResources shows exactly the resources you want to index with the SiteAtoZ snippet in the order you want (and no extra resources thrown in).

Once the resources are listing correctly, duplicate the AzItemTpl chunk, so it won't be overwritten by upgrades. Call the new Tpl chunk MyAzItemTpl. Change the &tpl property in your getResources tag to match the name of your new Tpl chunk (&tpl=`MyAzItemTpl`). Clear the site cache and then make sure the output still looks good. If it doesn't, you probably misspelled something (in other words, the &tpl argument in the snippet tag doesn't match the name of the new Tpl chunk). Once the new Tpl chunk is working properly, you can modify it to meet your needs.

All resource and TV fields should be available. Remember that if you show TVs in the Tpl chunk, you need to add &includeTVs=`1` &processTVs=`1` and &tvPrefix=`` (unless your TV names start with "tv."). If you will be showing the resource's content field (usually you won't need this), you'll need to include &includeContent=`1` as well.

Once everything looks the way you want it to and getResources shows all the resources you want to index in the order and format you want them shown, just change "getResources" to "SiteAtoZ" in the snippet tag on your AtoZDemo resource. Preview it again, and you should see your A to Z listing. Because SiteAtoZ passes all properties on to getResources, the selection should be exactly the same, but organized by first letter and with a set of jump links at the top of the page.

Note: The &resources property can only be used to exclude resources (&resources=`-12,19`), using it to include docs not work because getResources will include those resources regardless of any other criteria, and they will be included in every alphabet section.

Once you have the A to Z listing, you can add any of the optional properties listed below.

Basic Usage

[[!SiteAtoZ? &parents=`6` &tpl=`MyAzItemTpl`]]

Using pdoResources

By default SiteAtoZ uses getResources, but you can add &element=`pdoResources` to the tag and it will use pdoResources for the search. Be sure that you have the pdoTools package installed. Some properties may have to be modified for pdoResources, but pdoResources can be significantly faster than getResources.

The pdoResources snippet is included in the pdoTools extra.

Non-English Alphabets (diacritics)

(Most of the credit for this feature goes to Marek Woźniak for his extensive testing during its development.)

By default, SiteAtoZ uses the English alphabet: A,B,C, ... Z. Most diacritics will be handled fine with this method, but if you have pagetitles that begin with a diacritic, like these: Ć, ć, Ę, ę, Ł, ł, Ń, ń, Ó, ó, Ś, ś, Ź, ź, some of those pages might not show up in the listing. If so, you can use the &alphabet property tell SiteAtoZ to use an alternative alphabet, like this:

&alphabet = `A,B,C,D,E,F,G,H,I,J,K,L:Ł,M,N,O,P,Q,R,S:Ś,T,U,V,W,Z:Ź:Ż`;

Notice that the letters that should be treated as versions of the same letter, like Z:Ź:Ż are separated with colons rather than commas. The pages that start with any of the colon-separated letters will be grouped together in the listing.

You only need to be concerned about diacritics that can appear as the first letter of a pagetitle. Many diacritics will be handled correctly even if you don't list them in the alphabet property, but there's no harm in listing them all. It will slow down the page loading by a few milliseconds, but you can avoid this by marking the page as cacheable, and/or calling the snippet cached.

Multiple Calls to SiteAtoZ on the Same Page

This is possible as of SiteAtoZ Version 1.3.3. Each call will create its own list, with its own alphabetical jumplist at the top.

You can, for example show pages from separate contexts on the same page, even with duplicate pagetitles, without worrying about the links going to the wrong pages. As long as you use the &context property correctly in each tag (and optionally, the &alphabet property for multilingual sites), the links and the pagetitles will be correct.

Note that the JavaScript option doesn't work properly with this feature. If you want to use the JS option, you need to put the calls to SiteAtoZ on separate pages.

Context Awareness

The &context property can be used to select the context for each call to SiteAtoZ. If you leave it out, the context set in the default_context System Setting will be used.

By using the &context property, pages in different contexts will be appropriate for that context, and the context name will become part of the anchor for the jumplist. The links of the jumplist will also conform to any alias-related context settings that may differ between contexts, such as use_alias_path, or friendly_alias_urls.

The &where Property

As of version 1.3.0, SiteAtoZ will let you use a JSON string for the &where property in the tag (thanks to jSewill). This allows you to set additional criteria, such as limiting the output to selected templates, like this:

    &where=`{"template:=":1}`
    &where=`{"template:IN":[1,3,7]}`
  

See the examples at the bottom of this page for the proper formatting of the property.

Regardless of your &where property, SiteAtoZ will still divide the output using the alphabet. If your &where property is overly complex, it may not work.

Properties

Required Properties

• &parents - (string) Comma-separated list of ID's of container documents you want included (`0` for all docs)
• &tpl - (string) Tpl chunk used to format each entry; Default 'AzItemTpl'

Optional Properties

• &useNumbers - (boolean) Put a number array in front of the alphabet' default '0'
• &combineNumbers (boolean) group 0-9 titles together; default '0'
• &useAlphabet - (boolean) Use the Alphabet; default: '1' (set to '0' if all titles are numbers)
• &context - (string) Context you would like to display; Default: default_context System Setting
• &alphabet - (string) Comma-separated list of letters to use as headings to use for non-English alphabets; Default: 'A,B,C,D,..., Z'.
• &headingSeparator - (string) separator to use between letters in heading; Default ' | '
• &alphabetHeadingStart - (string) Letter to start with; Default: 'A' (useful for putting separate sections of the alphabet on different pages)
• &alphabetHeadingEnd - (string) Letter to end with; Default: 'Z'
• &title - (string) Field to used for search; Default: pagetitle (other common options: longtitle, alias, menutitle); Prefix this with tv (no dot) to use a TV for the search; this should match the first placeholder in your Tpl chunk
• &headingLinksTpl - (string) A tpl containing the entire A-Z heading (useful if you'd like to use images)
• &noData - (string) String to show if search comes up empty
• &cssFile - (string) Path to CSS file; use `0` for no CSS file
• &useJS - (boolean) Use JavaScript to hide results until a letter is clicked on
• &element - (string) Snippet to use; defaults to getResources
• &showUnsearchable - (string) Show docs marked as unsearchable; default: false
• &where - (string) JSON-formatted string containing search criteria

All other properties are those of getResources. They should all work as they do for getResources with one exception:

• &resources can be used to exclude documents (e.g., &resources=`-2,24`), but not to include them.

Troubleshooting

• Make sure getResources or pdoTools is installed
• If you use pdoTools, put &element=`pdoResources` in the snippet tag.
• If jumplist links later in the alphabet don't work, make sure they are not interfered with by other parts of your page design.
• Be sure to include a &context property in the snippet call.

Copyright © 2011-2023
Bob Ray