AliasPlugin < TWiki

<!--

   PLEASE DO NOT EDIT THIS TOPIC

   It is automatically generated from the subversion repository, and any changes
   you make will simply be overwritten the next time a release is generated.

   Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author.
-->
---+!! <nop>AliasPlugin
%TOC%
---++ Description
<table style="float:right">
<tr>
  <td><img src="%ATTACHURLPATH%/wikiringlogo40x40.png"></td>
  <td><a href="http://wikiring.de" title="Make your Wiki ring!" style="text-decoration:none">
      Powered by <br /> <nop>WikiRing Consultants </a>
  </td>
</tr>
</table>
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 =&lt;web&gt;.&lt;topic&gt;=
it will be replaced by an appropriate TWiki link. Aliases take only effect within the boundaries
if _alias areas_ between %<nop>STARTALIASAREA% and %<nop>STOPALIASAREA% tags.  

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

---++ Configuration
Configuration of this plugin is done by writing 
your aliases into a specific topic, the <nop>WebAliases. This topic is looked up
in three places: 
   1 the current web
   1 the %MAINWEB% web
   1 if there's no <nop>WebAliases topic in the %MAINWEB% it will be looked up in the %TWIKIWEB% 
The aliases defined in (1) are merged with those in (2) or (3). Thereby you can define
site-wide aliases in <nop>%MAINWEB%.WebAliases and  web specific aliases in the current's web <nop>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* | 
| %<nop>ALIASES% | display all aliases | 
| %<nop>ALIASES{regex="on"}% | display also the regular expression to match the alias | 
| %<nop>ALIASES{"&lt;topic&gt;" merge="on,off"}% \
| use aliases defined in &lt;topic&gt; by either merging or redefining the set of current aliases |
| %<nop>ALIAS{name="..." value="..." [regex="..."]}% \
  | defines an alias using =regex= to find it;\
    if =regex= is not specified it defaults to the alias' name |
| %<nop>STARTALIASAREA% | mark the beginning of an alias area |
| %<nop>STOPALIASAREA% | mark the end of an alias area |
| %<nop>UNALIAS% | delete all aliases |
| %<nop>UNALIAS{name="..."}%,%<nop>UNALIAS{"..."}% | deletes one alias |

The =regex= parameter in the %<nop>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:

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


The aliases in the topic <nop>WebAliases topic can be either defined using the %<nop>ALIAS{}%
macro or listed in the following way:
<verbatim>
   * <name1>: <value1>
   * <name2>: <value2>
   * <name3>: <value3>
   ...
</verbatim>

---++ Defined Aliases
%ALIAS{name="TESTLINK" value="%TWIKIWEB%.WebHome"}%
%ALIAS{name="TESTALIAS" value="yes"}%
%ALIAS{name="rtfm" value="read the fine manual"}%
%ALIASES%

---++ Plugin Installation Instructions

   * [[%ATTACHURL%/AliasPlugin.zip][Download]] the ZIP file
   * Unzip ==%TOPIC%.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 %MAINWEB%.TWikiPreferences and prepend to your SKIN variable the =alias= identifier,
     for example to
     <verbatim>   * Set SKIN = alias,pattern</verbatim>
     This surrounds the textarea with the STARTALIASAREA, STOPALIASAREA tags to mark the area where
     aliases are inserted.

---++ Test-Cases
%STARTALIASAREA%
| *&nbsp;* | *Pattern* | *Substitution* | *Correctness* |
|  1 | TESTLINK | yes, this is a link to <nop>TWiki.WebHome | %Y% |
|  2 | TESTALIAS | yes | %Y% |
|  3 | _TESTLINK | no, =_= is no word boundary | %Y% |
|  4 | TESTLINK_TESTLINK | no, =_= is no  word boundary | %Y% |
|  5 | <u>TESTLINK</u> | yes | %Y% |
|  6 | TESTLINKTESTLINK | no, this is _one_ word not being aliases | %Y% |
|  7 | rtfm | yes, but be more polite to your users | %Y% |
|  8 | <a href="%SCRIPTURL%/TESTALIAS%SCRIPTSUFFIX%" title="TESTALIAS">TESTALIAS</a> | this should be a green link to <nop>%SCRIPTURL%/<nop>TESTALIAS%SCRIPTSUFFIX% | %Y% |
|  9 | [[TWiki.WebHome][TESTALIAS]] | no, don't substitute inside a TWiki tag | %Y% |
|  10 | [[TESTALIAS]] | no, don't substitute inside a TWiki tag | %Y% |
|  11 | [<nop>[TESTALIAS]] | no, not even inside a _nopped_ TWiki tag | %Y% |
|  12 | <font color="red"> TESTALIAS </font> | yes, ignores =red= | %Y% |
|  13 | %RED% %TESTALIAS% %ENDCOLOR%  | no, inside two =%= | %Y% |
|  14 | %RED%%TESTALIAS%%ENDCOLOR%  | no, this is inside two =%= | %Y% |
|  15 | <font color="red"> %TESTALIAS% </font>  | no. inside two =%= | %Y% |
|  16 | <font color="red">%TESTALIAS%</font>  | no. inside two =%= | %Y% |
|  17 | %TESTALIAS | yes, no =perc= on the same line | %Y% |
|  18 | %TESTALIAS | yes, with a second =%= here | %Y% |
|  19 | %BLABLA TESTALIAS% | yes, this is no regular TWiki tag | %Y% |
|  20 | %BLABLA{TESTALIAS}% | no, this is a regular TWiki tag | %Y% |
|  21 | %<nop>BLABLA{TESTALIAS}% | no, albeit this is a _nopped_ TWiki tag | %Y% |
%STOPALIASAREA%

---++ Plugin Info
<!--
   * Set SHORTDESCRIPTION = Define aliases which will be replaced with arbitrary strings automatically
-->
|  Plugin Author: | TWiki:Main/OthelloMaurer, TWiki:Main/MichaelDaum |
|  Copyright &copy;: | 2003, Othello Maurer; 2003-2007, Michael Daum http://wikiring.de |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Version: | v2.20 |
|  Change History: | &nbsp; |
|  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 |
| &nbsp; | added fix to honor order of alias/unalias commands in a topic |
|  23 Mar 2005: | TWiki:Main/MichaelDaum: added list of test-cases |
|  &nbsp; | rewrite of substitution code |
|  &nbsp; | 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 |
|  &nbsp; | configured via a list now (was tables) |
|  &nbsp; | taking care not to replace inside html tags |
|  1 Dec 2003: | TWiki:Main.NielsKoldso: Non TWiki.WikiWord aliases as an option | 
|  &nbsp; | 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/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |

-- TWiki:Main/OthelloMaurer - 09 Oct 2003 %BR%
-- TWiki:Main/MichaelDaum - 13 Nov 2007
This topic: TWiki > AliasPlugin
Topic revision: r0 - 2007-09-14 - 20:29:19 - TWikiContributor
Copyright © 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