Finds and lists all pages that are referred to by the current page. (twin sister of ReferringPagesPlugin)
The depth parameter allows to display a recursive tree of referred pages.
--DF Aug 2004 , ([Rationale]) , Jan 2005 (added sorting)

Parameters #

page='<pagename>'
The name of the root page. Default is the name of the calling page.
type='local|external|attachment'
Local shows all local wiki links.
External shows all external links of the root page.
Attachment shows the referred attachments of the root page. You can combine the different types like in type='local attachment' Default is local.
depth='1..8'
Number of levels of wiki links to be expanded. Default is one.
include='<pattern>'
Only show links matching the include pattern[1]. (eg. 'BUG.*|CHANGE.*')
exclude='pattern'
Never show links matching the exclude pattern[1]. (eg. 'LeftMenu.*|Main')
format='full|sort'
Format full will display all referred page links with duplicate links as normal text but are expanded as normal. Default format will suppress duplicate page links.
Format sort will sort the referred page links alphabetically. Default format shows all referred page links in order of appearance.

Example#

Some valid examples :

 
    [{ReferredPagesPlugin depth='2'}]
    [{ReferredPagesPlugin page='Main' depth='2' format='sort' }]
    [{ReferredPagesPlugin page='Main' depth='2' include='JSP.*|.*Tag' format='full'}]
    [{ReferredPagesPlugin page='About' type='external' include='.*\.com.*'}]

The output of the plugin may look like this[2][3] :

<pagename>


Notes#

[#1] This plugin uses the PERL regular expression syntax, which is more powerful than the standard unix globbing syntax.
The main difference is that any char is matched by means of a explicit dot "." ; multiple occurences of any char are thus matched by means of ".*", ".+" or ".?".
See also overview of regular expression syntax

[#2]Hover your mouse over the <pagename> link and you will see all the settings of the called plugin.

[#3]The whole output of the plugin is enclosed in a <div class='ReferredPagesPlugin'> tag, so you can do any special formatting you want via the jspwiki.css.

[Why]
Although JSPWiki pages are by nature organised as a set of flat files, it is still very natural to organise related information in a more or less hierarchical way. Typically you start of with an overview page, adding links to detailed sub sections and sub sub sections.
I find myself often doing this using a page prefix (sometimes delimitted by a .) to keep related stuff together.

This plugin helps me to automatically keep an overview of such related pages an the tree of links which have been setup.

I am using it in combination with collapsable list tags, to navigate more easily longer lists.


Very cool, I put it up to see what it would do with my Main page. Is there some reason you did not alpha sort the entries?

I modified the code to allow the duplicates to have active links (fulllink option). Quick way to get a full site map at level=4. Thanks for the code! -- Foster Schucker

What version of JSPWiki did you test this against? It still compiles against the version I'm using (2.1.103-alpha), but I'm getting a misbehavior in the plugin: the WikiEngine is reporting too few attachments up to the plugin. The problem seems to occur after the WikiEngine.textToHTML() call on line 200. -GM
The plugin was developped on 2.1.86. So far, I didn't notice any problems on later versions, but never tried a recompilation. --DF


This plugin is now included in 2.3.25 (with some simplifications, the new ReferenceManager allows direct queries to page reference lists, so it is now a lot faster, too).

-- JanneJalkanen

Design ideas#

I want to list all the tips from page Wiki.Help.Tips, so I have this in a page [{ReferredPagesPlugin page='Wiki.Help.Tips'}]

However I get a list like

* Wiki.Help.Tip1
* Wiki.Help.Tip2
* Wiki.Help.Tip3
* Wiki.Help.Tip4

so, I would like to get rid of "Wiki.Help." :) What about something like: [{ReferredPagesPlugin page='Wiki.Help.Tips' domain='Wiki.Help.'}] so the ReferredPagesPlugin knows it shouldn't show the domain in the list of links... (other words instead of 'domain': context, hide, ignore,... In fact 'hide' might be useful and used in other places to hide parts of the link.) --Adler

2) new parameter#

what about adding this parameter before='#' so we can list items with other thing than bullets... it could be possible to not have bullets at all and make them separated wither by <br> or something else. --Adler

Problems#

I cannot really understand what this plugin does. I tried the following [{ReferredPagesPlugin include='Category*' exclude='Home' depth='8'}] I have several pages like "Category..." and the line above, in the 'Home', just return a link to 'Home'. I was expecting a list of all Category pages and not expecting 'Home'
Try [{ReferredPagesPlugin include='Category.*' exclude='Home' depth='8'}] This plugin uses Regular Expressions, not UNIX Glob expressions.--DF

Still it doesn't work. What I get is just the name of the page, 'Home' although I have the option exclude='Home'

If I understood correctly this plugin should create an index of all the 'links' on the page where this plugin is used. or?... --Adler

thank you for the reality check :) however it doesn't work for me :( my code [{ReferredPagesPlugin page='Category Projects' include='Project.*' depth='3'}] and I get one link "Category Projects"... instead of the links on that page that start with "Project". The page "Category Projects" has a few links to projects (these links are generated by using [{ReferringPagesPlugin}], is that problem?). I also created several links starting by "Project" but not even those appear here. --Adler

Reality check:#

[{ReferredPagesPlugin page='BrushedTemplate' include='Brushed.*' exclude='JSPWikiCSSDesign' depth='2'}]
This will list all pages referred to by the BrushedTemplate page; if following condition matches: the links should start with Brushed and may not be match the JSPWikiCSSDesign link.


Back to JSPWikiPlugins

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-1) was last changed on 24-May-2008 13:26 by -jim