Skip to content

Commit

Permalink
Item10232: PleaseFeelFreeToModify, DBRECURSE clone
Browse files Browse the repository at this point in the history 
Implemented using Foswiki::Func::query instead of DBCache. The code is
annoying, but committing in its current state for now. Mostly works. Sadly,
It re-implements the damn search formatting thingy, simply because I wanted
to do some fancy separator magic (leaf-to-branch vs branch-to-branch separators)
and I couldn't see that happening with the core formatter(s).

Does try to use list iterators, lazy-loading, etc.

git-svn-id: http://svn.foswiki.org/trunk/TopicRecursePlugin@10563 0b4bb1d4-4e5a-0410-9cc4-b2b747904278
  • Loading branch information
PaulHarvey authored and PaulHarvey committed Jan 16, 2011
0 parents commit cb32269
Show file tree
Hide file tree
Showing 9 changed files with 929 additions and 0 deletions.
33 changes: 33 additions & 0 deletions data/System/TopicRecursePlugin.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
%META:TOPICPARENT{name="Plugins"}%
---+ Topic Recurse Plugin

%SHORTDESCRIPTION%

<!--
One line description, required for extensions repository catalog.
* Set SHORTDESCRIPTION = %$SHORTDESCRIPTION%
-->

Aims to provide an alternative to:
* Foswiki:Extensions.TreePlugin, which is hard-wired to topic parent relationship, and doesn't allow delayed macros in the format string
* Foswiki:Extensions.DBCachePlugin DBRECURSE, which has a subtly different query syntax and bypasses the configured Query and Search implementations

%INCLUDE{"VarTOPICRECURSE"}%

---++ Installation
%$INSTALL_INSTRUCTIONS%

---++ Plugin Info

| Author: | Foswiki:Main.PaulHarvey |
| Copyright: | &copy; 2010-2011, Paul.W.Harvey@csiro.au TRIN http://trin.org.au/ &amp; %BR%\
Centre for Australian National Biodiversity Research http://anbg.gov.au/cpbr %BR%\
&copy; 2008-2011, Foswiki Contributors |
| License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
| Release: | %$RELEASE% |
| Version: | %$VERSION% |
| Change&nbsp;History: | <!-- versions below in reverse order -->&nbsp; |
| 04 Nov 2010 (0.1) | Foswikitask:Item9874 - Initial version |
| Home: | http://foswiki.org/Extensions/%TOPIC% |
| Support: | http://foswiki.org/Support/%TOPIC% |
| Development: | http://foswiki.org/Development/%TOPIC% |
79 changes: 79 additions & 0 deletions data/System/VarTOPICRECURSE.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
%META:TOPICINFO{author="ProjectContributor" date="1287902127" format="1.1" version="$Rev$"}%
%META:TOPICPARENT{name="Macros"}%
<blockquote class="foswikiHelp">%X% This plugin is incomplete. "%X%" against parameters, tokens means they aren't yet implemented. Lack of an %X% means the functionality exists or is untested...</blockquote>

#VarTOPICRECURSE
---+++ TOPICRECURSE{"&lt; topic &gt;" ...} -- traverse related topics
* Traverse topics related by some %SYSTEMWEB%.QuerySearch expression in a recursive (tree-like) pattern, Eg. =parent.name='$super'=
* Syntax: =%<nop>TOPICRECURSE{"&lt; topic &gt;" ...}%=
* Supported parameters:
| *Parameter:* | *Description:* | *Default:* |
| ="Web.SomeTopic"= %BR% \
=root="Web.SomeTopic"= | 'Root', or starting topic. The initial value of =$super= in the =query= param on the first iteration. | =%<nop>BASETOPIC%= (current topic) |
| =query="&lt;= [[%SYSTEMWEB%.QuerySearch][QuerySearch expression]] =&gt;"= | %SYSTEMWEB%.QuerySearch expression to apply at each recursion step; may be thought of as generating a list of children for a given parent. See [[#QueryTokens][query tokens]] for a list of special tokens allowed in the query string. | =parent.name='$supertopic'= |
| =header="..."= %BR% \
=footer="..."= | Custom format results: see [[FormattedSearch]] for usage &amp; examples | =*Search: '$rootquery'*$n= %BR% =*Total: $ntopics*= |
| =format="..."= %BR% \
=formatbranch="..."= %BR% \
=formatleaf="..."= | Custom format results: see [[FormattedSearch]] for usage &amp; examples; "branch" format is for nodes which have descendents; "leaf" format is for terminating nodes for which there are no others below. | =$indent* [<nop>[$web.<nop>$topic][$topic]]= |
| =separator="..."= | Separator _between_ search hits. See [[#FormatTokens]] | =$n= |
| =nodelimit= | Maximum number of nodes to be displayed. 0 = no limit. | =999= |
| =depthlimit= | Maximum depth to recurse to. 0 = no limit. | =0= |
| =breadthlimit= %X% | Maximum number of nodes to be displayed _at a given depth_. 0 = no limit. | =0= |

#QueryTokens
---++++ Query Tokens
Each "iteration" is a query that produces a list of children under a particular parent which itself is a result of a query under some super-parent (and so-on). That query may have the following tokens:
| *Name* | *Expands To* |
| =$root=, =$rootweb=, =$roottopic= | =root= param |
| =$super=, =$superweb=, =$supertopic= | The topic under consideration (which will be the parent to the topics in the query result) in a given iteration. Same as =$root[web%VBAR%topic]= on first iteration. |
| =$depth= | The =$super= topic's zero-based depth below =$root=. |
| =$nodeindex= | The =$super= topic's zero-based index among all rendered nodes of the entire =TOPICRECURSE= expression. |
| =$siblingindex= | The =$super= topic's zero-based index among its siblings. |
<blockquote class="foswikiHelp">%X% No other [[FormatTokens][tokens]] are supported in the =query= param</blockquote>

#FormatTokens
---++++ Standard Tokens
| *Name* | *Expands To* |
| =$web= | Name of the web |
| =$topic= | Topic name |
| =$parent= | Name of parent topic; empty if not set |
| =$locked= %X% | LOCKED flag (if any) |
| =$date= %X% epoch seconds | Time stamp of last topic update, e.g. =%GMTIME{"$day $mon $year - $hour:$min"}%= |
| =$isodate= %X% | Time stamp of last topic update, e.g. =%GMTIME{"$year-$mo-$dayT$hour:$minZ"}%= |
| =$index= | number of total results - can be used as a running counter in the =format=, or in the =footer=. This =$index= is not affected by web based partitioning of results. |
| =$item= | the full name of a result item - in a SEARCH context, equivalent to =$web.$topic= |
| =$rev= | Number of last topic revision, e.g. =4= |
| =$username= | Login name of last topic update, e.g. =jsmith= |
| =$wikiname= | Wiki user name of last topic update, e.g. =<nop>JohnSmith= |
| =$wikiusername= | Wiki user name of last topic update, like =%USERSWEB%.<nop>JohnSmith= |
| =$createdate= %X% epoch seconds | Time stamp of topic revision 1 |
| =$createusername= | Login name of topic revision 1, e.g. =jsmith= |
| =$createwikiname= | Wiki user name of topic revision 1, e.g. =<nop>JohnSmith= |
| =$createwikiusername= | Wiki user name of topic revision 1, e.g. =%USERSWEB%.<nop>JohnSmith= |
| =$summary= %X% | Topic summary, just the plain text, all formatting and line breaks removed; up to 162 characters |
| =$formname= | The name of the form attached to the topic; empty if none |
| =$formfield(name)= %X% =(works but bypasses Foswiki::Form::...renderFor*= | The field value of a form field; for example, if FAQWhatIsWikiWiki was a search hit, =$formfield(<nop>TopicClassification)= would get expanded to =%QUERY{"'FAQWhatIsWikiWiki'/TopicClassification"}%=. This applies only to topics that have a [[DataForms][DataForm]]. For multi-line textfields new lines are replace by an HTML &lt;br /&gt; |
| =$ntopics= | Number of topics found in current web. This is the current topic count, not the total number of topics |
| =$nhits= | Number of hits if =multiple="on"=. Cumulative across all topics in current web. Identical to =$ntopics= unless =multiple="on"= |
%INCLUDE{"FormatTokens"}%

---+++ =TOPICRECURSE= Format Tokens
| *Name* | *Expands To* |
| =$depth= | Branch depth, starting at 1 (the level below the root node) |
| =$indent= | 3 spaces per depth |
| =$indent(&lt;string&gt;)= | Repeats =&lt;string&gt;= _depth_ times |
| =$ntopicsdepth= %X% | Number of topics found in current web at the current _depth_ |
| =$ntopicsbranch= %X% | Number of topics found in current web in the current branch |
| =$indexdepth= %X% | Running counter of topics found in current web at the current _depth_ |
| =$indexbranch= %X% | Running counter of topics found in current web in the current branch |
| =$nodepath= %X% | Comma separated list of =$indexdepth= for all depths between the root node and current, representing the "path" by =$indexdepth= to the current node. |

---++++ Separator tokens
| *Name* | *Expands To* |
| =$nextweb=, =$nexttopic=, =$nextwebtopic= %X% | =$web.$topic= of the next node |
| =$prevweb=, =$prevtopic=, =$prevwebtopic= %X% | =$web.$topic= of the previous node |
%STOPINCLUDE%
---
*Related topics:* FormattedSearch, QuerySearch
<!-- %JQREQUIRE{"chili"}% -->
118 changes: 118 additions & 0 deletions lib/Foswiki/Plugins/TopicRecursePlugin.pm
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# See bottom of file for default license and copyright information

=begin TML
---+ package TopicRecursePlugin
=cut

package Foswiki::Plugins::TopicRecursePlugin;
use strict;
use warnings;

use Foswiki::Func (); # The plugins API
use Foswiki::Plugins (); # For the API version

our $VERSION = '$Rev$ (06-11-2010)';
our $RELEASE = '0.1.0';

our $SHORTDESCRIPTION =
'Query topics recursively, inspired by DBCachePlugin\'s DBRECURSE';
our $NO_PREFS_IN_TOPIC = 1;

my $coreLoaded;
my $debuglevel;

=begin TML
---++ initPlugin($topic, $web, $user) -> $boolean
* =$topic= - the name of the topic in the current CGI query
* =$web= - the name of the web in the current CGI query
* =$user= - the login name of the user
* =$installWeb= - the name of the web the plugin topic is in
(usually the same as =$Foswiki::cfg{SystemWebName}=)
=cut

sub initPlugin {
my ( $topic, $web, $user, $installWeb ) = @_;

# check for Plugins.pm versions
if ( $Foswiki::Plugins::VERSION < 2.0 ) {
Foswiki::Func::writeWarning( 'Version mismatch between ',
__PACKAGE__, ' and Plugins.pm' );
return 0;
}

$coreLoaded = 0;
Foswiki::Func::registerTagHandler( 'TOPICRECURSE', \&_TOPICRECURSE );

# Plugin correctly initialized
return 1;
}

sub _TOPICRECURSE {
my ( $session, $params, $topic, $web, $topicObject ) = @_;

if ( not $coreLoaded ) {
require Foswiki::Plugins::TopicRecursePlugin::Core;
Foswiki::Plugins::TopicRecursePlugin::Core::init();
$coreLoaded = 1;
}

return Foswiki::Plugins::TopicRecursePlugin::Core::TOPICRECURSE( $session,
$params, $topic, $web, $topicObject );
}

sub writeDebug {
my ( $message, $method, $level, $package, $refdebuglevel ) = @_;
my @lines;

if ( not defined $refdebuglevel ) {
$refdebuglevel =
( $debuglevel
|| $Foswiki::cfg{Plugins}{TopicRecursePlugin}{Debug}
|| 0 );
}
if ( $refdebuglevel and ( not defined $level or $level <= $refdebuglevel ) )
{
@lines = split( /[\r\n]+/, $message );
foreach my $line (@lines) {
my @packparts = split( /::/, ( $package || __PACKAGE__ ) );
my $logline = '::'
. $packparts[ scalar(@packparts) - 1 ]
. "::$method():\t$line\n";

if ( defined &Foswiki::Func::writeDebug ) {
Foswiki::Func::writeDebug($logline);
}
else { # CLI
print STDERR $logline;
}
}
}

return;
}

1;

__END__
Foswiki - The Free and Open Source Wiki, http://foswiki.org/
Copyright (C) 2010-2011 Paul.W.Harvey@csiro.au, TRIN http://trin.org.au/ &
Centre for Australian National Biodiversity Research http://anbg.gov.au/cpbr
Copyright (C) 2008-2010 Foswiki Contributors. Foswiki Contributors
are listed in the AUTHORS file in the root of this distribution.
NOTE: Please extend that file, not this notice.
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version. For
more details read LICENSE in the root of this distribution.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
As per the GPL, removal of this notice is prohibited.
8 changes: 8 additions & 0 deletions lib/Foswiki/Plugins/TopicRecursePlugin/Config.spec
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# ---+ Extensions
# ---++ TopicRecursePlugin
# ---+++ Debug
# **NUMBER**
# 0 = no debug log output, 1 = some, 2 = lots, 3 = maximum, 4 = insane
$Foswiki::cfg{Plugins}{TopicRecursePlugin}{Debug} = 0;

1;

0 comments on commit cb32269

Please sign in to comment.