Feature Proposal: BRAINSTORMING: Core equivalent of DBRECURSE

Motivation

Without DBCachePlugin's DBRECURSE, it's impossible to do anything useful with topic hierarchies and networks (from TML anyway). Example: Why should we need META{"parent", or BreadCrumbsPlugin? How can I traverse a series of topics that are linked via some value of a DataForms field?

Description and Documentation

We need a core macro that can do what DBRECURSE does (and maybe a little more).

It would be highly desirable to enhance QUERY and FORMAT, however neither are able to work with hierarchical (only flat) datasets.

This proposal may drive enhancements of those macros.

Requirements:

• Forward traversal (DBRECURSE already does this). You specify a starting topic and the macro applies a (filter) query at each recursion step. Each recursion step is essentially another flat list of results. Example (list all descendents of Some.Topic):

  %FOORECURSE{startref="Some.Topic" query="parent.name='$ref'"}%

• Reverse traversal, example (list all ancestors of Some.Topic):

  %FOORECURSE{startref="Some.Topic" query="'$ref'/parent.name"}%

• Complex formatting requirements: sub-headings/formats/footers, however as experience with DBRECURSE has shown, need to carefully control semantics of format tokens when a node is printed twice (once in a parent list, another when a node has its own children and thus gets its own heading - can be complex to work around this artifact when the application expects nodes to only be rendered once)

Examples

Impact

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

-- Contributors: PaulHarvey - 06 Oct 2010

Discussion

%FOORECURSE{
  query="LinkProperty=~'\b$ref\b'"
  root="Some.Network"
  header="Links to $root ($dollarroot at this level will always be Some.Network):$n"
  footer="All links: $nhits, to $root: $ntopics ($dollarntopics includes innerformat hits of this root level=1)"
  separator="<!-- $prevtype=('leaf' OR 'inner'), $nexttype=('leaf' OR 'inner') -->$n"
  leafindent="   "
  leafformat="$indent* [[$web.$topic][$topic]] has no links beyond this level ($level - should be 1 under $root)
    Also, root should be same as $dollarsuper=$super at level=1"
  innerheader="Links to $super, which is level $level (= 1 for topics adjacent to $root):$n"
  innerindent="   "
  innerformat="$indent* [[$web.$topic][$topic]] is $level deep (could=1 if below $root)"
  innerfooter="Links to $super: $ntopics"
  zeroresults="$root had no links to it..."
}%

Alternative 'generate' form (allows non-System.QuerySearch TML expressions to generate topic list at each iteration), equivalent of above is:

%FOORECURSE{
  generate="$percentQUERY{\"LinkProperty=~'\b$ref\b'\"}$percent"
  root="Some.Network"
  header="Links to $root ($dollarroot at this level will always be Some.Network):$n"
  ...
}%

Breadcrumbs example:

%FOORECURSE{
  query="parent.name='$ref'"
  root="%BASEWEB%.%BASETOPIC%"
  header="<span class='patternHomePath foswikiLeft'><span class='patternHomePathTitle'>You are here: </span>"
  leafformat="<a title='Topic revision: $percntREVINFO$percnt' href='$percntSCRIPTURLPATH{\"view\"}$percnt/$web/$topic'>$topic</a>"
  innerformat="[[$web.$topic][$topic]]"
  separator="<span class='foswikiSeparator'>&gt;</span>"
  footer="<span class='patternRevInfo'>($percntREVINFO{format=\"$date\"}$percnt)</date>"
}%

-- PaulHarvey - 09 Oct 2010