AliasPlugin

Define aliases which will be replaced with arbitrary strings automatically

Description

This plugin allows you to create arbitrary word aliases. If you write down a word that has a defined alias, it will then be replaced with the given text string. If that string is a string of the format <web>.<topic> it will be replaced by an appropriate TWiki link. Aliases take only effect within the boundaries if alias areas between %STARTALIASAREA% and %STOPALIASAREA% tags.

Aliases aren't replaced within html tags (<html tag ... TESTALIAS ... >), TWiki tags (%INCLUDE... TESTALIAS ...%) and TWiki links ([[TWiki.WebHome][TESTALIAS]]). A word can be prevented of being substituted by prefixing it with <nop>.

Configuration

Configuration of this plugin is done by writing your aliases into a specific topic, the WebAliases. This topic is looked up in three places:

  1. the current web
  2. the Main web
  3. if there's no WebAliases topic in the Main it will be looked up in the TWiki

The aliases defined in (1) are merged with those in (2) or (3). Thereby you can define site-wide aliases in Main.WebAliases and web specific aliases in the current's web WebAliases topic. Aliases can also be defined within the current topic, that is they will only be taking effect on the current topic. Similarly, aliases can be disabled. See the Syntax section for more details.

By default no alias substitution is applied to a page. You can configure all of your TWiki pages to get alias substitution by

  1. prepending alias to your SKIN variable in your TWikiPreferences/WebPreferences/topic preferenes
    Set SKIN = alias, pattern
  2. appending ?cover=alias to an url or
  3. by specifying so called "alias areas": an alias area is specified using the %STARTALIASAREA% ... %STOPALIASAREA% tags; these can occur multiple times on a page (note: nested alias areas aren't supported).

Syntax

This is the list of TWiki tags defined by this plugin.

Name Description
%ALIASES% display all aliases
%ALIASES{regex="on"}% display also the regular expression to match the alias
%ALIASES{"<topic>" merge="on,off"}% use aliases defined in <topic> by either merging or redefining the set of current aliases
%ALIAS{name="..." value="..." [regex="..."]}% defines an alias using regex to find it; if regex is not specified it defaults to the alias' name
%STARTALIASAREA% mark the beginning of an alias area
%STOPALIASAREA% mark the end of an alias area
%UNALIAS% delete all aliases
%UNALIAS{name="..."}%,%UNALIAS{"..."}% deletes one alias

The regex parameter in the %ALIAS{...}% tag might contain the two variables $start and $stop that help to match the boundaries of an alias consisting of non-alphabetic characters. Textile example:

%ALIAS{name="''" regex="$start''$stop" value="&rdquo;"}%
%ALIAS{name="``" regex="$start``$stop" value="&ldquo;"}%
%ALIAS{name="-" regex=" - " value=" &ndash; "}%
%ALIAS{name="--" regex=" -- " value=" &mdash; "}%
%ALIAS{name="(c)" regex="$start\(c\)$stop" value="&copy;"}%
%ALIAS{name="(r)" regex="$start\(r\)$stop" value="&reg;"}%
%ALIAS{name="(tm)" regex="$start\(tm\)$stop" value="&trade;"}%
%ALIAS{name="..." regex="$start\.\.\.$stop" value="&hellip;"}%
%ALIAS{name=",," regex="$start,,$stop" value="&bdquo;"}%
%ALIAS{name="1/2" regex="$start1/2$stop" value="&frac12;"}%
%ALIAS{name="1/4" regex="$start1/4$stop" value="&frac14;"}%
%ALIAS{name="3/4" regex="$start3/4$stop" value="&frac34;"}%

The aliases in the topic WebAliases topic can be either defined using the %ALIAS{}% macro or listed in the following way:

   * <name1>: <value1>
   * <name2>: <value2>
   * <name3>: <value3>
   ...

Defined Aliases

Name Value
TESTALIAS yes
TESTLINK TESTLINK
rtfm read the fine manual

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

File: Description:
data/TWiki/AliasPlugin.txt  
data/TWiki/WebAliases.txt  
lib/TWiki/Plugins/AliasPlugin.pm  
templates/body.alias.tmpl  
templates/view.alias.tmpl  

  • Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.
  • Edit your TWikiPreferences and prepend to your SKIN variable the alias identifier, for example to * Set SKIN = alias,pattern. This surrounds the textarea with the STARTALIASAREA, STOPALIASAREA tags to mark the area where aliases are inserted.

Test-Cases

  Test Should be Comment
1 TESTLINK TESTLINK yes, substitute: this is a link to TWiki.WebHome
2 yes yes yes
3 _TESTLINK _TESTLINK no substitution: _ is no word boundary
4 TESTLINK_TESTLINK TESTLINK_TESTLINK no: _ is no word boundary
5 TESTLINK TESTLINK yes
6 TESTLINKTESTLINK TESTLINKTESTLINK no: this is one word not being aliases
7 read the fine manual read the fine manual yes, but be more polite to your users
8 yes yes yes
9 TESTALIAS TESTALIAS no, don't substitute inside a TWiki tag
10 TESTALIAS TESTALIAS no, don't substitute inside a TWiki tag
11 [[TESTALIAS]] [[TESTALIAS]] no, not even inside a nopped TWiki tag
12 yes yes yes, ignores red
13 %TESTALIAS% %TESTALIAS% no, inside two %
14 %TESTALIAS% %TESTALIAS% no, this is inside two %
15 %TESTALIAS% %TESTALIAS% no, inside two %
16 %TESTALIAS% %TESTALIAS% no, inside two %
17 %yes %yes yes, no perc on the same line
18 %yes %yes yes, with a second % here
19 %BLABLA yes% %BLABLA yes% yes, this is no regular TWiki tag
20 %BLABLA{TESTALIAS}% %BLABLA{TESTALIAS}% no, this is a regular TWiki tag
21 %BLABLA{TESTALIAS}% %BLABLA{TESTALIAS}% no, albeit this is a nopped TWiki tag

Plugin Info

Plugin Author: TWiki:Main/OthelloMaurer, TWiki:Main/MichaelDaum
Copyright: © 2003, Othello Maurer;
© 2003-2008, Michael Daum http://michaeldaumconsulting.com;
© 2003-2010 TWiki:TWiki/TWikiContributor
License: GPL (GNU General Public License)
Version: v2.32
Change History:  
2010-04-26 TWikibug:Item6433 - doc improvements
28 Apr 2008: speed improvements
13 Nov 2007: Item4959: disabled settings in plugin topic, removed DEFAULT_ALIASES
14 Sep 2007: added view.alias.tmpl
13 Sep 2007: rewrite for modern TWiki engines
10 Feb 2006: fixed use of uninitialized value (outch)
03 Feb 2006: prevent nested alias expansion; support convenience aliases for anchors on the same page
09 Dec 2005: added expl icite regex parameter for ALIAS
06 Dec 2005: fixed deprecation warning on a dakar install; added support for non-alphabetical aliases; fixed use of uninitialized values due to special chars in alias patterns; the ALIAS tag in WebAliases can be used to define global aliases now
27 Apr 2005: always read site aliases and then merge in web aliases
07 Apr 2005: TWiki:Main/MichaelDaum: major rewrite
30 Mar 2005: TWiki:Main/MichaelDaum: added alias area
  added fix to honor order of alias/unalias commands in a topic
23 Mar 2005: TWiki:Main/MichaelDaum: added list of test-cases
  rewrite of substitution code
  improved configurability
22 Mar 2005: TWiki:Main/MichaelDaum: prevent substitutions within html tags, twiki tags and twiki links
21 Mar 2005: TWiki:Main/MichaelDaum: allow arbitrary string substs
  configured via a list now (was tables)
  taking care not to replace inside html tags
1 Dec 2003: TWiki:Main.NielsKoldso: Non WikiWord aliases as an option
  More alias prefixes allowed
16 Oct 2003: Speedup
09 Oct 2003: Initial Version
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/AliasPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/AliasPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/AliasPluginAppraisal

Related topics: WebAliases, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory