AutoLink

Summary: automatically displays any specified word, phrase or name as a link, throughout the entire site
Version: 2010-02-15
Prerequisites:
Status:
Discussion: AutoLink-Talk
Categories: Links
Users: +1 -1 (View / Edit)

Questions answered by this recipe

How can I have a particular word, name, or phrase automatically display as a link to a particular site?

Description

automatically displays any specified word, phrase or name as a link, throughout the entire site.

Notes

autoLink.phpΔ displays any specified word, phrase or name as a link, throughout the entire site. To enable this recipe, create SiteAdmin.AutoLink and add your names and urls one-per-line, in the format:

	john doe|http://johndoe.com
	jane doe|http://janedoe.com

Note that:

  • all names as declared here must be completely lowercase in order for this to work - all subsequent conversions of names-to-links on your actual wikipages are case-insensitive...
  • adding spaces around the pipe "|" may result in an error:
    • correct:   name|url
    • possibly problematic:   name | url
  • you can comment out individual lines by adding # or // to the beginning of a line
  • a different pagename or group can be used to store autolinks by declaring something like $AutoLinkPage = 'Site.AutoLink';

Then in config.php, include the recipe via:

	# enable autolink recipe:
	include_once('cookbook/autoLink.php');

Names and phrases can also be defined in config.php instead of (or in addition to) posting them on SiteAdmin.AutoLink, by simply declaring $AutoLinkArray['name'] = 'url' before including the recipe. For example:

	# reminder: all keys must be completely lowercase in order for this to work!
	$AutoLinkArray['john doe'] = 'http://johndoe.com';
	# enable autolink recipe:
	include_once('cookbook/autoLink.php');

Note that AutoLink replacement can be prevented by preceding any word or phrase with the backtick (`) character. For instance `John Doe will display as John Doe - minus the backtick, and without any auto-linking. If you'd prefer a different escape-character, or would like to use multiple escape-characters, you can supply it via $AutoLinkEscapeChars.

	# backtick (`) and forward-slash (/) - the latter so that blam.com/name won't trigger
	$AutoLinkEscapeChars = "`\/";

To turn AutoLink off for an entire page, simply add (:AutoLink: 0:) to the page.

In addition, by adding $AutoLinkRemovePrefix = "_"; to config, then any definition with an underscore in front will have the underscore removed later on, for example:

	if you define: _john doe|http://johndoe.com
	then typing _john doe will result in: [[http://johndoe.com|john doe]]

Finally, by default AutoLink causes each instance of a defined word or phrase to be linked. However, autolinking can be limited to only affecting the first instance of each word or phrase by setting in config.php:

	$AutoLinkOnce = true;

$AutoLinkOnce can also be enabled for a single page via the PTV (:AutoLinkOnce: true:). To enable this, add the following to config.php before including the recipe:

	# be able to turn AutoLinkOnce on/off on a page via (:AutoLinkOnce: true:)
	if (PageTextVar($pagename, 'AutoLinkOnce')) {
		if (PageTextVar($pagename, 'AutoLinkOnce')=="true") $AutoLinkOnce = true;
		else $AutoLinkOnce = false;
	}

Example:

If using the $AutoLinkArray declared above:

john doe turns into %newwin%[[http://johndoe.com|john doe]]
John Doe turns into %newwin%[[http://johndoe.com|John Doe]]
_John Doe turns into %newwin%[[http://johndoe.com|John Doe]]   (if $AutoLinkRemovePrefix = "_";)
`John Doe remains John Doe

Issues

names with ampersands require a special declaration

if you want "jane & john" to always be automatically converted to [[http://janeandjohn.com|jane & john]], you must substitute "&" for "&" in your AutoLink declaration on SiteAdmin.AutoLink:

  • works: jane & john|http://janeandjohn.com
  • doesn't: jane & john|http://janeandjohn.com

order of declarations

Be careful with your order of declarations on your AutoLink page. For instance, if you want to replace 'John Doe' with a link to http://johndoe.com, and 'John Doe's Workpage' with a link to http://JohnDoeWorkSite.com, you'll need to declare the longer version of the name first, as in:

John Doe's Workpage|http://JohnDoeWorkSite.com
John Doe|http://johndoe.com

Release notes

  • 2010-02-15 - can now turn AutoLink off per page by adding (:AutoLink: 0:) to the page
  • 2009-12-25b - added ability to remove a prefix via $AutoLinkRemovePrefix
  • 2009-12-25 - minor change: changed $page var to something less common ($alpage); changed name of markup from 'names' to 'autolink'
  • 2009-10-06 - added $AutoLinkOnce capability (a suggestion of Gustav) - autoLink-2009-10-06.phpΔ
  • 2009-09-01c - added $AutoLinkEscapeChars to recipe, which permits custom declaration of escape characters (the default being backtick (`) - autoLink-2009-09-01c.phpΔ
  • 2009-09-01b - added 'addslashes' and 'stripslashes' to recipe, to fix a problem where apostrophes were preventing autolinking - autoLink-2009-09-01b.phpΔ
  • 2009-09-01 - 1) added ability to define autolinks on SiteAdmin.AutoLink; 2) simplified markup to a single line; (special thanks to PeterBowers for help with both 1. & 2.!!) 3) renamed $NameToLinkArray to $AutoLinkArray. - autoLink-2009-09-01.phpΔ
  • 2009-08-26 - initial release - autoLink-2009-08-26.phpΔ

See also

Contributors

this code based on contributions by:

Comments

See discussion at AutoLink-Talk

User notes +1 -1: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.