2021-12-05, 17:16

Feb 27, 2012 — Notify Users module, ver. 0.5 released — user can choose between sending single message (...) »

2013-01-28, 08:32

19 студзеня 2013 у Гродне трагічна загінуў паэт, журналіст і мой сябар (...) »

2009-10-14, 07:19

The site Litaratura.org is devoted to Belarusian literary works and translations. (...) »

2009-01-12, 20:46

Late November 2008 marked the 20th anniversary of the official founding of the Belarusian (...) »

Registered User Area Log into This Site
Show Credits... Credits
~ / Public Domain Software / Extensions to Ditto / Glossary Extender $_
Glossary Extender
Click To View A Full Size Image...
2010-06-25, 22:00

Ditto’s extender is an opportunity for defining custom placeholders and/ or filters without interfering into snippet’s core code.

Particularly, a custom filter is an interesting thing — it is a callback function that the core code executes on each item in the final dataset.

My glossaryFilter extender allows you to easily generate listings of documents depending on the value of document’s pagetitle or user-selected attribute.

glossaryFilter in action

This example lists documents from the global scope of my site...

... with the use of form buttons...

... or simple links...

0-9 | A | B | A, C | C-F | G-K | L | M, Z | Cyr А-Я | Ж | З | П | Т | У | Х | Clear Listing

This example filters documents by matching aliases...

0-9 | A | B | A, C | C-F | G-K | L | M, Z | N-Y | Clear Listing

How it works?

Specific listings are achieved with a simple Ditto call.

Ditto call used to generate „G-K” listing

[[Ditto? &parents=`0` &depth=`0` &display=`all` &sortBy=`pagetitle` &sortDir=`ASC` &extenders=`glossaryFilter` &filterBy=`G-K` &tpl=`@CODE:<p>[+pagetitle+]</p>`]]

Having such extender working with Ditto snippet you can either build your glossary manually (by typing each Ditto call required for generating specific listing) or you can automate it by overlaying Ditto with a new snippet that will build the full index within a loop.

Scenario for „manual” glossary

You can build, for example, the following document’s structure for your glossary...

Glossary on multiple pages

Index      <- list children with „traditional” Ditto
+- 0-9     <- list 0-9 docs with „extended” Ditto
+- A       <- list A docs with „extended” Ditto
+- B       <- list B docs with „extended” Ditto
+- C-F     <- list C-F docs with „extended” Ditto
+- ...
+- M-Z     <- list M-Z docs with „extended” Ditto

... or you can call all „extended” Dittos on a single page, then wrap each call with an unique div-id-container, and finally switch visibility of div-id-containers with JavaScript (jQuery).

Scenario used on this page

Three examples at the top of this article are powered by custom snippets that dynamically build the index and then, depending on user’s request, generate required listing of documents (by calling „extended” Ditto).

Some technical details or „What I can type within filterBy parameter?”

glossaryFilter selects documents by matching pagetitles with regular expression. By default, filterBy parameter is passed into the following regular expression:

RegExp used to match document’s pagetitles

/^[...]/iu (&forceUTF8=`1`)

Ellipsis stands for the value of your filterBy parameter. In the terms of regular expressions, the above construct (its square bracket part) is called character class. Within filterBy parameter you should avoid to use characters having special meaning for reqular expression itself. But, apart from that, you can use syntax covering almost 100% of typical needs.

Possible syntax for filterBy parameter

&filterBy=`A`   get documents whose pagetitles start with A
&filterBy=`A-D` get documents whose pagetitles start with A, B, C, or D
&filterBy=`AD`  get documents whose pagetitles start with A or D
&filterBy=`^AD` get documents whose pagetitles start neither with A nor with D

Also I have added three more parameters to my glossaryFilter extender — filterMode, filterVar, and forceUTF8.

Possible values for filterMode are: class, custom, chunk. &filterMode=`class` (the default value) means that the value of filterBy is passed into RegExp’s character class (see above) while &filterMode=`custom` means that within filterBy parameter you are providing your own and full-featured regular expression – you are responsible for both its syntax and logic! (If you are unfamiliar with regular expressions, simply do not use this extra mode.) &filterMode=`chunk` is similar to custom, but the RegExp string is provided with a chunk whose name is held within filterBy. Providing RegExp string directly within filterBy parameter (custom mode) is possible, but due to the interference with MODx tags it is highly onerous action.

With the use of filterVar parameter you can easily change a criterion used by the extender for matching documents – if you omit this parameter, then pagetitle is used by default.

forceUTF8 parameter set to 1 causes that filterBy value is treated as UTF-8 string. This parameter affects extender’s behavior while it is running in &filterMode=`class` (the default mode).


In the attachment section you have download links to the both my glossaryFilter extender for Ditto and snippets used in examples on this page. These things are released under the terms of General Public License — code is provided „as is” and, what is more important from my point of view, if you are unable for some reasons to get these things working, it is mostly your problem, not mine.

Download This Attachment... glossaryFilter Extender — the very latest version
Last modified: 2010-08-30, 00:00 — Size: 2,83 KB
Download This Attachment... Three snippets used in examples on this page
Last modified: 2010-08-30, 00:00 — Size: 2,98 KB