WhatLinksHere

<< FourOhFour Cache | Cookbook-V1 | Smart Quotes >>

Note: The recipes here are for PmWiki versions 0.6 and 1.0 only. For PmWiki 2.0 recipes, see Cookbook.

Goal

To provide backlinks; that is, to show what other pages link to a particular page. This can be useful for updating or changing pages, or for doing site architecture.

Solution

Attach:pmwiki-whatlinkshere-0.1.tar.gz

Attach:pmwiki-whatlinkshere-0.1.zip

Discussion

Requirements

This package was created with PHP 4.3.4, but it should work with lesser versions of PHP with some massaging.

It was created using PmWiki 1.0.3, but should work with PmWiki 0.6 or above.

Installation and configuration

Installing files

You should be able to just unpack this tarball (or zipfile) and then copy all its contents recursively to your pmwiki directory::

    tar zxvft pmwiki-whatlinkshere-0.1.tar.gz
    cp -R pmwiki-whatlinkshere-0.1/* /path/to/pmwiki/

Configuring PmWiki

To activate this extension, add the following line to your PmWiki local/config.php file:

    include_once('cookbook/whatlinkshere.php');

It should work correctly by default.

Configuration variables

These are the config variables that affect how the whatlinkshere module works. You probably don't have to mess with any of these.

$LinkRules: An array of rules for determining if one page links to another. The rules are implemented as functions; see *Customizing rules* below for more info.
$DependRules: An array of rules for determining if one page depends on another. The rules are implemented as functions; see *Customizing rules* below for more info.
$LinksListItemFmt: A chunk of HTML shown for each found item on the What links here page. Defaults to '<dd><a href="$PageUrl">$Title</a></dd>'.
$LinksListGroupFmt: A chunk of HTML shown for each group of items on the What links here page. Defaults to '<dt><a href="$ScriptUrl/$Group">$Group</a> /</dt>'.
$WhatLinksHereFmt: The HTML for the "content area" of the output page. Defaults to "<h2 class='wikiaction'>What links here</h2>\n<dl>\$LinksMatchList</dl>\n<h2 class='wikiaction'>Dependencies</h2>\n<dl>\$DependsMatchList</dl>".
$LinksListEmptyFmt: What to show when there's no linked/depending pages. Defaults to 'No matches.'.
$HandleWhatLinksHereFmt: The full HTML output by the whatlinkshere action. Unless there's a good reason, you probably shouldn't mess with this. Defaults to your template wrapped around the contents of the $WhatLinksHereFmt variable.

Using the extension

The extension can be useful both for users and for developers.

whatlinkshere action

This extension provides an action to show the backlinks for a page. You may want to add this action to your template somewhere, like so:

     $PageUrl?action=whatlinkshere

This will show a list of all pages that link to this page, as well as any pages that "depend" on the page (for example, that include or redirect to it).

You can customize the output using the $*Fmt configuration variables specified above.

Functions

For developers, this module provides two helpful functions.

WhatLinksHere($pagename): Returns an array of names of pages that link to the page identified by $pagename. Tries to catch all the ways a page can link to another page (free links, wiki words, etc.)
WhatDependsOn($pagename): Returns an array of names of pages that depend on the page identified by $pagename. Tries to catch all the ways a page can depend on another page (sidebars, group headers and footers, includes, redirects, etc.)

Customizing rules

By default, this package should handle the wiki syntax that PmWiki comes with. However, PmWiki allows you to customize the wiki syntax in (almost) arbitrary ways. I tried to make this package flexible enough so you can add new rules pretty easily, and disable existing rules.

Disabling rules

You can disable rules by setting their value in the rules list to false. For example, if you've disabled WikiWords in your wiki, you can keep them from showing up as links by adding this code to your local config:

    $LinkRules['groupwikiword'] = false;
    $LinkRules['barewikiword'] = false;

You should probably do this after including the package.

The default link rules are:

barewikiword: WikiWords with no group prefix.
groupwikiword: WikiWords with a group prefix.
barefreelink: Free links without a group prefix.
groupfreelink: Free links with a group prefix.

The default dependency rules are:

groupheader: A page depends on its $Group/GroupHeader page (unless [[nogroupheader]] is set).
groupfooter: A page depends on its $Group/GroupFooter page (unless [[nogroupfooter]] is set).
groupsidebar: A page depends on its $Group/SideBar page.
mainsidebar: All pages depend on the Main/SideBar page.
bareinclude: Including a page in the same group ([[include:SomePage]]).
groupinclude: Including a page with a group prefix ([[include:SomeGroup.SomePage]]).
bareredirect: Redirect to a page in the same group ([[redirect:AnotherPage]]).
groupredirect: Redirect to a page with a group prefix ([[redirect:SomeGroup.AnotherPage]]).

Creating new rules

You can create a new link or dependency rule by adding a new rule function and adding it to the appropriate rules array. For example:

    $LinkRules['mylink'] = 'MyLinkRuleFunction';

You should probably put this after the line that includes the whatlinkshere.php module in your config file.

A rule function has to work as follows:

RuleFunction($pagename1, $pagename2, $page2): Returns true if the page named $pagename2 depends on or links to $pagename1. $page2 is the page data for $pagename2; you can get to the source of $pagename2 with $page2['text'].

History

July 2, 2004: version 0.1.

Comments & Bugs

There're probably lots. Some notable ones:

Performance. It works pretty slow. I'd like to find bottlenecks and squash them.
Wimpy regexps. The regular expressions used for the default rules are pretty optimistic; there are probably a lot of false negatives and false positives that need to be found. Bug reports for this are especially appreciated.
Difficult to extend. It's kind of a pain to add new rules; I'd like to make it easier.
Redirects and includes are shown as WikiWord links, too. I'll try and nail this down a little better for version 0.2.

Contributors

EvanProdromou

Copyright

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.

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. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA This software's available under the GNU General Public License (GPL) version 2 or later.

I've tried to get the script working for a WikiFarm. With no success.
Acutally in one field I copied the php into the coobook and added include_once('cookbook/whatlinkshere.php'); to local/config.php. This shows the backlinks but the script also displays a Warning: Cannot add header information.
I've checked all the php-files involved, there is no trailing whitespace to cause that warning.
What should I do? pmwiki-2.3.38 -- Last modified by {{SteffenGlueckselig}}

from IP: 85.171.160.186