AliasPlugin
Define aliases which will be replaced with arbitrary strings automatically
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 of this plugin is done by writing your aliases into a specific topic, the WebAliases. This topic is looked up in three places:
- the current web
- the Main web
- 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
- prepending
alias to your SKIN variable in your TWikiPreferences/WebPreferences/topic preferenes Set SKIN = alias, pattern
- appending
?cover=alias to an url or
- 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).
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="”"}%
%ALIAS{name="``" regex="$start``$stop" value="“"}%
%ALIAS{name="-" regex=" - " value=" – "}%
%ALIAS{name="--" regex=" -- " value=" — "}%
%ALIAS{name="(c)" regex="$start\(c\)$stop" value="©"}%
%ALIAS{name="(r)" regex="$start\(r\)$stop" value="®"}%
%ALIAS{name="(tm)" regex="$start\(tm\)$stop" value="™"}%
%ALIAS{name="..." regex="$start\.\.\.$stop" value="…"}%
%ALIAS{name=",," regex="$start,,$stop" value="„"}%
%ALIAS{name="1/2" regex="$start1/2$stop" value="½"}%
%ALIAS{name="1/4" regex="$start1/4$stop" value="¼"}%
%ALIAS{name="3/4" regex="$start3/4$stop" value="¾"}%
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>
...
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 |
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 |
|
|
|
Related topics: WebAliases,
TWikiPlugins,
DeveloperDocumentationCategory,
AdminDocumentationCategory
