Macro LookupDictPagesAndSort
Contents
Description
Goal
The aim of the macro LookupDictPagesAndSort is to:
- Lookup pages part of a page-group page - or search for pages that match a given first pattern
Inside these pages, lookup text matching definitions on either the pages themselves or related ones (like JonasSmedegaard/MyDict)
- All definitions found (=hits) are included in place of the macro call, sorted by a key given as a third pattern
- Each hit can be followed by a link to its page, and by a heading (a heading text found on its page, matching an optional given pattern)
The macro is based heavily on ../SearchInPagesAndSort, but adapted to work more "wiki-like", using pages, page groups and page definitions.
Macro synopsis
Usage:
[[ LookupDictPagesAndSort (KEYWORD=VALUE ... ) ]]
Search for 'lookuptext' definition in pages matching 'pages' pagegroup/regex, and sort the found definitions (=hits) in this order:
- substring of the hit matching 'sortkey'; group same matches of 'sortkey' by a header
- substring of the hit matching 'lookuptext'
Possible keywords:
Help = 0, 1, 2 Displays 1:short or 2:full help in the page. Default: 0 (i.e. no help). Pages = 'PAGES REGEX' Pages in which the text is sought. If or empty (default) search in the current page '+PageGroup' and defaults 'NoLinks' to 1. If starting with "+" then a single PageGroup page is looked up. Default: empty (i.e. current page). ExcludePages = 'PAGES REGEX' Exclude these pages (i.e. remove these pages from the list collected by 'Pages'). Default: empty (i.e. don't exclude any). LookupText = 'TEXT DICT' To lookup definition in matching pages. Mandatory! SortKey = 'TEXT REGEX' Criterion to sort matching lines (=hits). or Default: empty (i.e. no sorting). '@PN?Definition@' Heading = 'TEXT REGEX' Follow each hit by the text maching Regex, that preceeds the hit in its source page. Default: empty (i.e. no headings). UnassignedText = 'WIKI TEXT' Header for hits not matching the sort key. Default: '[unassigned]'. Reverse = 0 or 1 Reverse-sort the hits. Default: 0 (i.e. forward sort). RawText = 0 or 1 Do not format found text. Default: 0 (i.e. formatted). Format = 'STRING' Explicitly format the output using this string, which can contain wiki formatting as well as these tokens: @KT@ : text matching 'SortKey' @LT@ : text matching 'LookupText' @FT@ : line of text @PN@ : page name @HT@ : heading text @@ : the '@' character \\n : newline (of wiki source text). Each token can contain a regex acting as a filter for displaying the value, e.g: @FT:{[123]}@ displays the prio smiley Multiple groups can be defined, in which case the text matching them will be displayed, e.g: @FT:{[123]}(.*)@ displays text after prio Default: '' (i.e. auto-formatting). HeaderFormat = 'STRING' If specified, use this instead of 'Format' for headers. Default: '' (i.e. do not display headers). FormatSort = 0 or 1 If 1, sort the output generated by 'Format' (if 'Reverse' is 1, reverse-sort). If 0, leave the output sorted by the 'SortKey' criterion (if specified). Default: 0 (i.e. no sorting). NoHeader = 0 or 1 Disable showing the headers as subtitles. Default: 0 (i.e. show headers). NoLinks = 0 or 1 Disable following each hit by a link to its page. Default: 0 (i.e. show links) or 1 if 'Pages' is omitted. NoPageText = 'HTML TEXT' Text displayed if no page match 'Pages'. Default: an error message w/ Page regex NoText = 0 or 1 Disables showing the found text. Default: 0 (i.e. show found text).
Keywords can be also given in upper or lower cases, or abbreviated. Example: LookupText, lookuptext, LOOKUPTEXT, lt, LT, Pages, p, etc.
Download & Release Notes
Download |
Release Version |
Moin Version |
Release Notes |
|
1.5.x and (possibly) earlier |
|
HOWTO
Installing the macro
As usual, for any new macro:
Download the latest code: LookupDictPagesAndSort.py
Install in the Python location for MoinMoin macros (on a sample wiki on a Debian system: /var/lib/mywiki/data/plugin/macro/)
Examples
Sample 1:
Given a page named 'AnInterestingBook':
= A rather interesting Book = == Bibliographical facts == Title:: A rather interesting Book Author:: A. Man Publisher:: Cool Publishing Corp. == Comments == I really think that this book is worth a read. I'd even wanna lend out my copy if needed! == Status == Owner:: Jonas Smedegaard Availability:: Lend out to Jack the Ripper..and a page named 'AnotherInterestingBook':
= Another interesting Book = == Bibliographical facts == Title:: Another interesting Book Author:: A. Man Publisher:: Cool Publishing Corp. == Comments == This is the sequel to AnInterestingBook - also worth a read. == Status == Owner:: Jonas Smedegaard Availability:: Available - call me if interested in lending it..and a page named 'AnotherBoringBook':
= A boring Book = == Bibliographical facts == Title:: A pretty boring Book Author:: Some Fool Publisher:: Lousy Publishing Corp. == Comments == Don't waste time on this book. I was stupid enough to buy it once, but won't even lend it out! == Status == Owner:: Jonas Smedegaard Availability::- ..and the wiki setup to include books as dict pages:
page_dict_regex = u'[a-z0-9](Book|Dict)$'
..using the macro in a page named 'BookOverview' like this:
= Known books = [[LookupDictPagesAndSort(pages=".*Book$", lookuptext="Title")]] = Book availability = [[LookupDictPagesAndSort(pages=".*Book$", lookuptext="Availability")]]..will give this output (note: _text_ are links):
Known books * A. Man * A rather interesting Book _AnInterestingBook_ * A rather interesting Book _AnotherInterestingBook_ * Some Fool * A pretty boring Book _AnotherBoringBook_ Book Availability * Lend out to Jack the Ripper _AnInterestingBook_ * Available - call me if interested in lending it _AnotherInterestingBook_
Sample 2:
Given a page /MyDict containing:
== Contact info == FirstName:: Jonas FullName:: Jonas "dr. Jones" Smedegaard Phone:: +45 40843136 Email:: dr@jones.dk == Photo gallery == PhotoThumbnail:: http://dr.jones.dk/images/me/kp_bricks_thumb.jpg PhotoPortrait:: http://dr.jones.dk/images/me/kp_bricks.jpg- ..the following macro call in another page:
[[LookupDictPagesAndSort(lookuptext="+WikiEditorsGroup", DictPage="/MyDict", LookupText="Email", Format=" * @PN?PhotoThumbnail@ [mailto:@PN?Email@ @PN?FirstName@]\\n")]])]]
- ..will produce a list of images and email references for me and all other editors.
Tips
For help, insert just [[LookupDictPagesAndSort]] (i.e. without arguments) in your page and click Preview. The macro will insert its usage synopsis.
When sub-pages are sought unintentionally, it may be hard to understand why the results are unexpected. So be sure to terminate the Pages regex argument by '$' to limit the page matches.
- Modifications in preview mode of pages targetted by the macro will not be seen by the macro until the changes are saved.
Sample 3:
See a reallife usage of this macro http://wiki.homebase.dk/Top100Books
Misc
Todos
Author, contact
For comments, please just add a note below - I am subscribed to this page!
Please do not "correct" the indentation of this page: It is in sync with the script itself.
FeedBack
Thanks for your work on this useful macro. I have a question about your first example. It seems like the macro needs another keyword argument in order to produce the output that you displayed as Known Books. You show the macro as:
[[LookupDictPagesAndSort(pages=".*Book$", lookuptext="Title")]]
However, this macro does not specify the grouping by author that is displayed in your results:
Known books
* A. Man
* A rather interesting Book _AnInterestingBook_
* A rather interesting Book _AnotherInterestingBook_
* Some Fool
* A pretty boring Book _AnotherBoringBook_If my understanding is correct that an argument is missing from the example, could you please correct the macro to show what is needed to group books by author in this example? -- EMF 2024-11-24 22:22:01
Example one is intended as a "how simple can it possibly be?", so sorting is deliberately left out (but I now see several typos that should probably get fixed, but that's a different issue). -- JonasSmedegaard 2006-02-07 00:07:46.
I have tried to reproduce your sample 1 example in order to get a clearer picture of this macro's use. However, it does not report finding any of the pages. I know the macro itself is seen, as it inserts a useage synopsis when called with no arguments. Any suggestions how to troubleshoot? -Andrew
Make sure the pages used are actually recognized as dict pages, by querying them with [[GetVal()]]. -- JonasSmedegaard 2006-01-27 22:18:50
See also ../SearchInPagesAndSort - the "father" of this macro: Instead of operating on pages (using dict lookups for definitions::), it operates on lines (using regular expressions).