Finds and lists all pages that refer to the current page.

Parameters #

  • max=n : How many pages to list. Default is 10. Some pages might create very long lists, so it's a good idea to limit the list size.
  • maxwidth=n : Limits the length of the generated links to at most n characters. This should used to keep the LeftMenu or LeftMenuFooter at a manageable width. Default is to not limit the length at all.
  • separator=<markup> : What should be put between the different items. It's WikiMarkup, and by default it's two backslashes (meaning a carriage return, or <br />). JesseWilbur: If you want to use something like a "|", you have to put it in single quotes. separator='|'
  • page=<page name>
  • before=<markup>
  • after=<markup>
  • show=pages|count : This parameter can have two values, "pages" (the default), and "count". The value "pages" will give you the list containing the pages, the value "count" will give you just the number of pages, not the whole list.
  • showLastModified=true|false : The showLastModified parameter gives you the last modified date/time of the most recently changed page. It is only valid if show="count", otherwise a PluginException is thrown.

This plugin extends AbstractReferralPlugin and therefore inherits its parameters.


[{INSERT ReferringPagesPlugin}]
See LeftMenuFooter.


TomMalaher: It seems that the list of referring pages is not sorted alphabetically. This would seem to be useful. Perhaps even adding a sort parameter, with values like author, name, size, date. Plus a mechanism for choosing ascending/descending like: sort=+size or sort=-date.

Going even further, it would be nice perhaps to be able to choose what metadata is displayed. e.g author, size, date...

In 2.1.x collections of pages returned from the internals of JSPWiki are all sorted by name, so the ReferringPagesPlugin automatically shows sorted results. The metadata and sorting options would require changes to the plugin code. Sounds like a good idea to me, go write it. :^) --JohnV

It would be nice if the plugin could be configured so that it does not only output the data in one column, but in one or more lines of text. That way, the plugin could be placed not only in the left column (which seems to be the assumption now), but anywhere, i.e. the footer of a page. This would be an advantage if you are dealing with extremely long lists, and you don't want to truncate them. It would make the plugin much more general. H.O.P

You can use the "separator" parameter to define any WikiMarkup you want to insert between the items. By default, it's \\. --JanneJalkanen

It would be useful if the plugin would provide a tooltip (ALT) that contains the full name of the referring page. When referring page names are truncated, and we have many pages with similar names, it's good to know where a given link would take you. -- BernardFarrell

I use the referring pages plugin with the ReferringWithoutReferringPages to build categories. Only thing is, it doesn't seem to be accepting WikiMarkup for the separator value?? I am trying to create an ordered list for my category page, but it ignores
and inserts the \\ instead? If I use seperator='#', it prints the # itself, so why doesn't it create my ordered list when I am using valid WikiMarkup in the separator value?

Update! Don't use separator=, use the following syntax, at least it works for me with 2.2.x:#

[{INSERT ReferringPagesPlugin WHERE max=10 maxwidth=250 before='#' after='\n'}]
  1. Abstract Referral Plugin
  2. Brushed Edit Page Help
  3. Bug Do Not List This Page As Bug In New Bugs
  4. Bug Plugin Tag Not Writing Output
  5. Bug Reference Manager Does Not Find Singular References
  6. Bug Referring Page Plugin Page Param Does Not Work
  7. Bug Referring Pages Plugin Before With Wiki Markup Only Renderes The First Item
  8. Bug Referring Pages Plugin Dont Write Noboby After Filtering
  9. Bug Referring Pages Plugin Fails After Upgrade
  10. Bug Referring Pages Plugin Links Non Existing Pages

...and 25 more
-- BrandonKing

This issue is being tracked as BugSeparatorParameterNotAcceptingWikiMarkup. Please discuss there.

-- JanneJalkanen

Fixed in v2.1.152 -- AbstractReferralPlugin now also supports the separator parameters "before" and "after". Any of the plugins that use this(like the Referring Pages Plugin) give you extra control over the formatting. See Documentation Wiki for examples. -- Foster Schucker

ErikAlm, 09-Jun-2005: How about adding a parameter 'page' telling the plugin what page to display referring pages for (default would be 'this page').

Let's say I have a project main page. I want to have a list of project issues, project members, open project tickets... etc on this page.

I would then create the pages MyProjectIssue, MyProjectMember, MyProjectOpenTicket... and on my project main page I would do:

[{ReferringPagesPlugin page='MyProjectIssue'}]

[{ReferringPagesPlugin page='MyProjectMember'}]

!Open tickets
[{ReferringPagesPlugin page='MyProjectOpenTicket'}]

This way we could have several different lists of referring pages on one page.

A potential problem might be that we could cause infinite loops... But this is just a feeling I have and my head is too jumbled to figure out if it's a real or just imagined problem... :O

A side effect might be that we could get away with never linking to the 'category page' other than from the pages of that category (thus getting rid of the problem that pages that is not really of the category is displayed in the list as well).

Why? Because if we can list the referrals in any page (not just the page that is referred to) we do not have to link to the page where the list is. Hmmm, in fact... that page does not even have to contain a list of referrals at all... Maybe this would mess up the original concept of this plugin?

You're a bit late; the page param was added in 2.2.19 ;-) --JanneJalkanen

bug? This is a very useful thing! But did the approach above worked? I have a page "Project.Project1.Members" with a list of members (like, Member1, Member2, Member2...) then I have but I get "nobody"... or do you mean using "ReferredPagesPlugin"? --Adler

When using the before param tag with wiki markup, only the first item is rendered:
 [{INSERT com.ecyrd.jspwiki.plugin.ReferringPagesPlugin WHERE max=100, maxwidth=250, before='#'}] } 
-- Arent-Jan

Use the after parameter with \n as described further above. It works for me in 2.2.28. -- Gregor Hagedorn

I wanted to provide a link in my rather minimalist template (consisting of basically a small top and bottom menu and the rest is content) to another page that lists the pages that refer to the page that the user was on initially, rather than having to display all the referring pages on the same page. Is this possible? If not directly in content, then maybe in the JSP templates? -- KieronWilkinson

Since this plugin is also used to implement Categories (to gather all pages 'belonging to' a named category), wouldn't it be nice to be able to exclude certain pages (like a Menu or Sitemap)? An extra parameter would do the trick, as it does for the IndexPlugin. Should I mark this as a "bug" or a feature request? (Wouter)

It's implemented in 2.3.x already ;-)

ReferringWithoutReferringPages, JSPWikiCorePlugins

I'm seeing an issue with this on my wiki; when I just use the plain ReferringPagesPlugin call, my text shows up without spaces separating. For example, my page 'Product List' shows up as 'ProductList'.

--joshDM, 18-Apr-2006

On some old versions of JSPWiki this was true... Should be fixed with newer versions.

-- JanneJalkanen

Design suggestions#

When I want to list pages that use some prefixes (for organisation purposes or namespace) I end up with these examples, using the ReferringPagesPlugin:




As I suggested for other plugins I would like to have a parameter to hide parts of the link. So I could do this:

__List of tips__
[{ReferringPagesPlugin page='CategoryWikiTips' hide='WikiTip.'}]

to get this (note how the links need to be generated):

List of tips

Tip1 (though the link generated needs to be [Tip1|WikiTip.Tip1])

and so on. How does this sound? --Adler

I'm trying (unsuccessfully) to exclude pages from being listed using this plugin by using the exclude parameter that's defined in the AbstractReferralPlugin. Is this parameter supported in JSPWiki 2.1.142? It doesn't appear that the installation I'm using is configured to allow use of the ReferringWithoutReferringPages plugin. Are there any other options?

--Lynne Avery

The "exclude" parameter did not become available until 2.3.44. So you should upgrade to the latest 2.4 release.

-- JanneJalkanen

Problem with ReferringPagesPlugin#

We tryed to migrate the pages of a JSPWiki-Version 2.0.52 to a version 2.4.100. The problem is that the "old" pages seem to be ignored by the ReferringPagesPlugin of the new wiki. For example: There's one site, which provides an overview of all "categories" (which are of course the referring pages). At the old Wiki you'll get a nice overview... On the new wiki the page is empty except for the main - which is a new page. Requirement:

  • We can't update to a newer version than the 2.4.100 due to demand of the customer.
What we did already:
  • Emtpy the cache of lucene, restart - no effect.
  • Set the correct baseDir and baseURL - no effect.
Is there any possibility to force the plugin to do a "rescan"?

Thanks for any suggestions! -- Joachim

Remove the "refmgr.ser" file from the workDir. That forces a reindex!

(You should upgrade to 2.4.104 due to security reasons. Functionally it's the same as 2.4.100.)

-- JanneJalkanen

Count zero is shown as nobody...#

It would be nice if the ReferringPagesPlugin would show the count of the number of references even if that count is zero. At the moment instead of 0 it inserts the value for referringpagesplugin.nobody. The following change at line 119 of the source would fix the situation:

            // If nothing was left after filtering or during search
            final boolean noLinks = ( links == null || links.size() == 0 );

            if( m_show.equals( PARAM_SHOW_VALUE_COUNT ) )
                result = new StringBuffer();
                result.append( noLinks ? 0 : links.size() );
                if( m_lastModified )
                    result.append( " (" + m_dateFormat.format( m_dateLastModified ) + ")" );
	    else if ( noLinks )
                wikitext = rb.getString("referringpagesplugin.nobody");
                result.append( makeHTML( context, wikitext ) );
-- Andre van Dalen
Thank you!

Is there a way to target multiple pages? For example, I am trying to do something like this -

I have a category pages for 'Linux Shell' and 'Mac Shell' commands. There is a lot of overlap. I'd like to do something like -

INSERT ReferringPagesPlugin WHERE max=100 maxwidth=250 before='#' after='\n' page=CategoryComputing.Linux.Shell and page=CategoryComputing.Mac.Shell

--AnonymousCoward, 25-Sep-2009 19:07

I have the same problem: Is there any possibilty to refer to two pages at once? --Selina, 04-Oct-2010 10:45

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-68) was last changed on 04-Oct-2010 11:48 by