TWiki> TWiki Web>AliasPlugin (2007-09-14, TWikiContributor)EditAttach

AliasPlugin

On this page:

Description

Powered by
WikiRing Consultants
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.

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

  • Download the ZIP file
  • Unzip AliasPlugin.zip in your twiki installation directory. Content:
    File: Description:
    data/TWiki/AliasPlugin.txt  
    data/TWiki/WebAliases.txt  
    lib/TWiki/Plugins/AliasPlugin.pm  
    pub/TWiki/AliasPlugin/wikiringlogo40x40.png  
    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

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

Plugin Info

Plugin Author: TWiki:Main/OthelloMaurer, TWiki:Main/MichaelDaum
Copyright ©: 2003, Othello Maurer; 2003-2007, Michael Daum http://wikiring.de
License: GPL (GNU General Public License)
Version: v2.20
Change History:  
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

-- TWiki:Main/OthelloMaurer - 09 Oct 2003
-- TWiki:Main/MichaelDaum - 13 Nov 2007

Edit | Attach | Print version | History:  | Backlinks | Raw View | More topic actions
Topic revision: r0 - 2007-09-14 - 20:29:19 - TWikiContributor
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.AliasPlugin