SiteAtoZ Snippet Tutorial
I could tell you how many hours it takes to develop a MODX extra Transport Package complete with a build script, properties, multiple MODX elements, internationalized strings, error checks, and then fully test it, but you wouldn't believe me. 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-commercial 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.
Updates in Version 1.1.0-pl thanks to Jako. Other updates and bugfixes by Jsewill and isaacniebeling.
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.
- Create A to Z jump links to selected documents
- Tpl chunk for formatting each item in the list
- 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 and 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.
[[!SiteAtoZ? &parents=`6` &tpl=`MyAzItemTpl`]]
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.
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). See the examples at the bottom of this page for the proper formatting of the property.
As of Version 1.2.0-pl, documents marked as unsearchable are hidden by default. Use the &showUnsearchable property if you want to show them.
- &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'
- &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)
- &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
- &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.
If you have the book and would like to download the code, you can find it here.
If you have the book and would like to see the updates and corrections page, you can find it here.
MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:
- Installing MODX
- How MODX Works
- Working with MODX resources and Elements
- Using Git with MODX
- Using common MODX add-on components like SPForm, Login, getResources, and FormIt
- MODX security Permissions
- Customizing the MODX Manager
- Using Form Customization
- Creating Transport Packages
- MODX and xPDO object methods
- MODX System Events
- Using PHP with MODX
Go here for more information about the book.
Thank you for visiting BobsGuides.com
— Bob Ray