[pmwiki-users] new feature suggestion

[Patrick R. Michaud]

On Mon, Apr 11, 2005 at 08:51:11AM -0400, David Spitzley wrote:
> >>> "Patrick R. Michaud" <pmichaud at pobox.com> 04/10/05 5:26 PM >>>
> There are lots of other ways to format lists of pages (and metadata
> about them), they just aren't well documented yet.
> -----------------------------------------------
> 
> For those of us inclined to help with the documenting, what functions
> should we be looking at to make sure we've found all the format options
> in the core installation?

Well, one of the reasons it's not documented is that (:pagelist:) is on
the list of things to be completely rewritten, so there might be some minor
changes.  That said, here's my best shot at what currently exists...

PmWiki comes with two directives for generating lists of pages -- (:pagelist:)
and (:searchresults:).  The primary difference between the two is that
(:searchresults:) generates the "Results of search for ..." and "### pages
found out of ### searched" messages around the results -- otherwise they're
pretty much identical.

There are quite a number of options available.  

The "group=" parameter limits results to only those pages in a specific group.

The "trail=" parameter gets the list of pages to be displayed from a WikiTrail.

The list= option allows the search to include/exclude pages that
are in sets defined by the wiki administrator in config.php files.  PmWiki
predefines "list=normal", which excludes things like AllRecentChanges, RecentChanges,
GroupHeader, GroupFooter, GroupAttributes, etc., from being displayed in the
results.  Wiki administrators can define their own custom lists via the
$SearchPatterns array (see Cookbook.SearchResults).

Any argument that appears that isn't in the form 'key=value' is treated as text
that either must (or must not) exist in the page text.  Thus

    (:pagelist trail=PmWiki.DocumentationIndex list=normal apple -pie:)

lists all "normal" pages listed in the DocumentationIndex trail that contain
the word "apple" but not "pie".

Finally, the "fmt=" parameter determines how the resulting list should be 
displayed.  PmWiki predefines "fmt=simple", "fmt=bygroup", and "fmt=group",
and Cookbook.DictIndex adds "fmt=dictindex".  Cookbook recipes can add more
output formatting options via the $FPLFunctions array.  Several that are
planned are also "fmt=publish" to displays the contents of each page in
the list, "fmt=include" to include portions of a page's text, "fmt=category"
to display pages in a form suitable for category listings, and "fmt=menu"
to display the list as an expandable or dropdown menu.

Other options are on the drawing board for (:pagelist:)

    link=Group.SomePage          - all pages that have a link to Group.SomePage

    order=                       - sort the pages into some other sequence

    count=                       - display only the first ### pages

Pm