• View
• Edit
• History
• Attach
• Print
• Backlinks

Router

Questions answered by this recipe

• How can I make PmWiki urls look different?
• How can I make PmWiki fit into a pre-existing url structure?
• How can I make PmWiki use dashed-lower-case urls instead of CamelCaseUrls?

Installation

Place router.phpΔ in your cookbook directory.

Add the following lines near the top of your config.php file.

  $aRoute=array();
  #Routing instructions go here
  #$aRoute['PmWiki']='RoutedPmWiki';
  include('cookbook/router.php');

Router is most useful with $EnablePathInfo enabled but also works when it is disabled.

Usage Instructions

Router adds the page variable $GroupUrl that returns a routed url to the base page of the current group. Instead of using <a href='{$ScriptUrl}/{$Group}'>{$Group}</a> in a template file use <a href='{$GroupUrl}'>{$Group}</a>

Router expects to find an array of routing instructions in the global variable $aRoute. Routing instructions are processed first to last for inbound links and last to first for outbound links. Changes made by one instruction are passed on the the next instruction.

Routing instructions can be specified in a short and long format

Short Format:

  $aRoute['MatchPage']='MatchUrl';

Long Format:

  $aRoute[]=array(
    'Mode'=>'BeginsWith'
    ,'PageName'=>'MatchPage'
    ,'Url'=>'MatchUrl'
  );

Both instructions do the same thing. For an outbound link, they look for a page name that begins with "MatchPage" and substitute "MatchUrl" when a match is found.

http://example.com/MatchUrlGroup/MatchUrlPage translates to a pmwiki pagename of MatchPageGroup/MatchUrlPage

This instruction is symetrical, so the reverse is true for an outbound link. The short instruction form only uses the "BeginsWith" mode for matching.

Modes that currently exist are:

• Symetrical Modes
  • BeginsWith
  • Contains
  • EndsWith
  • ExactMatch
• Asymetrical Modes
  • RegReplace
• Special Modes
  • CamelCaseToLowerCase

Symetrical Examples:

Contains

$aRoute[]=array(
  'Mode'=>'Contains'
  ,'PageName'=>'MatchPage'
  ,'Url'=>'MatchUrl'
);

http://example.com/MatchUrlGroup/MatchUrlPage translates to
MatchPageGroup/MatchPagePage

EndsWith

$aRoute[]=array(
  'Mode'=>'EndsWith'
  ,'PageName'=>'MatchPage'
  ,'Url'=>'MatchUrl'
);

http://example.com/GroupMatchUrl/PageMatchUrl translates to
GroupMatchUrl/PageMatchPage

ExactMatch

$aRoute[]=array(
  'Mode'=>'ExactMatch'
  ,'PageName'=>'MatchPageGroup/MatchPagePage'
  ,'Url'=>'MatchUrlGroup/MatchUrlPage'
);

http://example.com/MatchUrlGroup/MatchUrlPage translates to
MatchPageGroup/MatchPagePage

Also

$aRoute[]=array(
  'Mode'=>'ExactMatch'
  ,'PageName'=>'Main/HomePage'
  ,'Url'=>''
);

http://example.com/ translates to
Main/HomePage

But more interestingly, Main/HomePage translates to
http://example.com/ for outbound links.

Asymetrical Modes

Asymetrical modes only work in one direction. The direction to apply the routing instruction to is specified by adding another element.

  ,'Direction'=>'Out' or
  ,'Direction'=>'In'

The 'Direction' element can be used with any instruction mode.

RegReplace Example

$aRoute[]=array(
  'Mode'=>'RegReplace'
  ,'Search'=>'/^MatchUrl/'
  ,'Replace'=>'MatchPage'
  ,'Direction'=>'In'
);

For inbound links,

http://example.com/MatchUrlGroup/MatchUrlPage translates to
MatchPageGroup/MatchUrlPage

But this instruction is limited to only inbound links, it is skipped when translating pagenames to urls for outbound links.

MatchPageGroup/MatchPagePage translates to
http://example.com/MatchPageGroup/MatchPagePage

So a related outbound instruction is needed.

$aRoute[]=array(
  'Mode'=>'RegReplace'
  ,'Search'=>'/^MatchPage/'
  ,'Replace'=>'MatchUrl'
  ,'Direction'=>'Out'
);

Now MatchPageGroup/MatchPagePage translates to
http://example.com/MatchUrlGroup/MatchPagePage

The RegReplace instruction simply passes the values of 'Search' and 'Replace' to the php preg_replace() function. If you specify a 'Limit' element in the routing instruction, that value will also be passed to preg_replace().

Special Modes

Special modes mess with urls in an extra special way. :)

CamelCaseToLowerCase Example

The 'CamelCaseToLowerCase' mode changes the entire pmwiki url structure from CamelCaseUrls to dashed-lower-case-urls. It functions in both directions unless you specifically add a 'Direction' element to the routing instruction.

$aRoute[]=array(
  'Mode'=>'CamelCaseToLowerCase'
);

http://example.com/url-group/url-page translates to
UrlGroup/UrlPage

and vice versa

When using CamelCaseToLowerCase in conjunction with the Apache mod-rewrite module, be sure to change your .htaccess to send all urls that start with lower case characters to index.php.

Create your own routing modes

Add a function named RT_ModeName to config.php before including router.php. The first parameter is the path and the second parameter is an array that contains a single routing instruction. The 'Direction' element is always present and indicates whether the path you are working on is for an inbound or outbound link. Router will add the 'Direction' element to the instruction array if it doesn't already exist. Be sure to return $path even if you don't change its value.

The following function creates a routing mode named "Redirect"

$aRoute[]=array(
  'Mode'=>'Redirect'
  ,'In'=>'Main/HomePage'
  ,'Out'=>'http://example.com/'
);

///
/// Redirect to specified location when path matches
///
function RT_Redirect($path,$aline) {
  if ('In'!=$aline['Direction']) {
    return $path;
  }
  if ($path==@$aline['In']) {
    header('Location: '.@$aline['Out'],TRUE,301);
  }
  return $path;
}

Release Notes

• 2007-12-19r12beta - Now only needs to be included from config.php
• 2007-11-20r11alpha - initial release

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

Comments