PermLinkPlugin

Manages permanent links to topics.

Usage

Anywhere in a topic or template:

%PERMLINK% called with no parameters returns a permanent link to the current topic.

Parameter	Description	Default
topic="Sandbox.TestTopic" topic="TestTopic"	Renders the permanent link of a different topic than the current. If the web part is left out, the current web is assumend.	current topic
warn="on" warn="off"	Show or suppress warning messages on faiures. Possible failures: - no ID available - read access to topic denied or - topic does not exist	on
format=""	Controls the format of the permanent link. See formatting variables below.	$url$md5

Formatting parameter	Description	Default
$url	Base URL without the ID. This parameter can be set in configure.	http://translate.foswiki.org/bin/rest/PermLinkPlugin/view/
$md5	permanent ID in MD5 format (hex)	none
$human	permanent ID in human readable format	none
$rev	Current Revision number (delimitted with two hyphens)	none

Plus the default escape sequences like $n or $percnt.

Example

Example	Rendered Version (fake)
%PERMLINK{ format="[[$url$md5$rev][Permlink]]" }%	[[http://some.host/foswiki/bin/rest/PermLinkPlugin/view/66ed41d6787c2833f78644336e5b9b7f--23][Permlink]]

Documentation

Terminology

The PermLinkPlugin knows two types of identifiers (IDs) to permanently point to a single topic:

• md5: 32 chars long, a hexadecimal number calculated with a standard MD5 hash algorithm based on the original topic name and a timestamp
• human: a human readable version based on the original web and topic name and optionally extended with a timestamp (in seconds)

ID deployment

On a fresh install (or on a system prior to the installation of this plugin) none of the topics carry an ID. Once the plugin is activated newly created topics as well as topics which go through an edit-save-cycle automatically get an ID. If you execute %PERMLINK% on a topic with no ID, you get a warning message. In that case just go through a normal edit-save-cycle.

If you are an administrator you can mass deploy IDs on a web basis. Copy the following URL into your browser and add alter the web parameter Foo to the webname you want to deploy IDs in.

http://translate.foswiki.org/bin/rest/PermLinkPlugin/deploy?web=Foo

CAUTION: This will alter all topic in that web. Be aware, that the "last modified" timestamp and author will be touched!

Revision specific permanent links

Permanent links can point to a specific revision of a topic or to the last revision (whatever that is). Revision specific links end in two hyphens (--) and a number (corresponding to the resivion number). If this suffix is omitted, the link will always lead to the latest revision. You can add this suffix by adding a $rev directly behind the $md5 or $human in the %PERMLINK% format option.

(Skin) Installation Instructions

This plugin is SKIN agnostic. It does not know anything about your SKIN. If you want to integrate this feature into your SKIN, you have to manually edit the template files or customisation topics of your SKIN. Just put a %PERMLINK{}% where you think it fits most.

Authentication Requirements

PermLinkPlugin uses the Foswiki API to specify that the deploy action requires an authenticated user, whereas the view action (used when following a permanent link) should not.

In order for PermLinkPlugin to resolve permanent links for guest users, the rest script should be removed from {AuthScripts} in configure.

• Foswiki 1.0.x: Turn on expert settings ("Yes, I have read all the documentation"). {AuthScripts} is under "Security Setup: Authentication"
• Foswiki 1.1.x: {AuthScripts} is under "User Logins" -> "Login"

Developer notes

The IDs are stored in local PREFerences called PERM_ID_MD5 and PERM_ID_HUMAN.

Info

Author(s):	Foswiki:Main.OliverKrueger
Copyright:	© 2009, Foswiki:Main.OliverKrueger, (wiki-one.net)
License:	GPL (Gnu General Public License)
Version:	6186 (2010-01-29)
Release:	1.0.0
Change History:
29 Jan 2010	Foswikitask:Item8346 - Add compatibility for Foswiki 1.0.x releases Foswikitask:Item8347 - Fix view action requires authentication
06 Jul 2009	Initial version
Dependencies:	None
Home page:	Foswiki:Extensions.PermLinkPlugin
Support:	Foswiki:Support.PermLinkPlugin