AutoLink
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
- correct:
- 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.