Find Elsewhere Plugin

Automatically link to another web(s) if a topic isn't found in the current web.

This is useful - for example - for a TWiki site that wants to implement a glossary/dictionary web where common terms are defined and stored. Without this plugin:

• Each web would need to create their own topic for a common term
• Link to or INCLUDE the topic from where it is defined
• Authors need to remember to put the Web name in front of the topic name, such as TWiki04x02.WikiWord

Without this kind of plugin, it's likely that common terms used within an organization will be defined in multiple webs or the common terms will be unlinked wiki words (as if they didn't exist).

Syntax Rules

No new syntax is introduced. However, new automatic WikiWord linking will occur.

If a topic is not found in the current web, this plugin will look through the webs listed in the LOOKELSEWHEREWEBS variable. If the topic is found (as it looks through the webs in their listed order), it will create one or more links, depending on the number of topics found.

Single hits

Test case Input Output (if installed) Expected Found here WebHome WebHome TWiki04x02 Found singular here WebHomes WebHomes WebHomes Found elsewhere WebSearch WebSearch WebSearch Found elsewhere TWiki.TWikiUsers TWikiUsers? TWikiUsers Found elsewhere [[TWiki.TWikiUsers][twiki users]] twiki users? TWikiUsers Found singular elsewhere WebSearches WebSearches WebSearches Found elsewhere, spaced wiki word [[Web search]] Web search Web search Found elsewhere, abbrev ACRONYM ACRONYM (If ACRONYM is a topic defined in one of the LOOKELSEWHERE webs, a link to it should show up) Escaped with <noautolink> <noautolink> WebSearch </noautolink> WebSearch WebSearch

(Note: FindElsewherePlugin doesn't support <noautolink> in TWiki-3; WebSearch will be found anyway if you're still using this codebase) |

Multiple hits

If a word is found in two or more LOOKELSEWHERE webs, a special syntax is used:

• Standard WikiWord: TWikiPreferences^(TWiki,Main)
• [[Spaced wiki word]]: TWiki preferences^{(TWiki04x02,Main)}

Create this table in Sandbox.FindElsewherePluginTest to try it out:

| *Test case* | *Input* | *Output<br/>(if installed)* | *Expected* |
| Found elsewhere | <nop>TWikiPreferences | TWikiPreferences | <nop/>TWikiPreferences<sup>([[%SYSTEMWEB%.TWikiPreferences][%SYSTEMWEB%]],[[%USERSWEB%.TWikiPreferences][%USERSWEB%]])</sup> |
| Found elsewhere, spaced wiki word | [<nop/>[TWiki preferences]] | [[TWiki preferences]] | <em>TWiki preferences</em><sup>([[%SYSTEMWEB%.TWikiPreferences][%SYSTEMWEB%]],[[%USERSWEB%.TWikiPreferences][%USERSWEB%]])</sup> |

Internationalization

FindElsewherePlugin handles international characters (I18N) in links, topics and webs.

Input Output FindElsewherePlugin#TopicAnchor FindElsewherePlugin#NewFunctionalityTest TWiki04x02.WebHome TWiki04x02 WebHome WebHome [[TWiki04x02.WebHome]] TWiki04x02.WebHome [[TWiki04x02.WikiWord]] TWiki04x02.WikiWord [[TWiki04x02.WikiWords]] TWiki04x02.WikiWords TWiki04x02.WikiWord WikiWord TWiki04x02.WikiWords WikiWords [[Main.WebSearch][This is a link to WebSearch in Main]] This is a link to WebSearch in Main

FindElsewherePlugin Hints

• You can en- or disable this plugin for webs, topics or users, using the standard TWiki preferences hierarchy
• You can avoid single words being looked up by using !DontLookup or <nop/>DontLookup syntax
• "Groups of webs" can use each other as lookup webs, by setting the LOOKELSEWHEREWEBS variable accordingly in their WebPreferences.

FindElsewherePlugin Settings

You can disable look elsewhere - sitewide (in TWikiPreferences), per web (in WebPreferences) or pr. topic by defining DISABLELOOKELSEWHERE = 1. You are encouraged to disable the plugin wherever it is explicitly used!

You can list other webs in which to look for topics that don't exist in the current web by defining LOOKELSEWHEREWEBS to be a comma-separated list of webs - for example, TWiki,Main

If the WikiWord is plural but doesn't exist, FindElsewherePlugin also looks for the singular word in other webs. You can disable this behaviour by setting DISABLEPLURALTOSINGULAR = 1. (Note this setting is for looking in other webs only (plural to singular is still automatically done in the current web).

Even if a link refers explicitly to the current web and a topic name (for example, [Thatweb.ThatTopic]], you can still trigger FindElsewherePlugin to look in other webs for that topic. To enable this behaviour for a web, define LOOKELSEWHEREFORLOCAL = 1 in the WebPreferences. This is particular useful when you have moved topics from one web to another, but you don't want to rewrite all the links in the source web.

Plugin Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.

Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.

• If you have TWiki 4.1 or later, you can install from the configure interface (Go to Plugins->Find More Extensions)
  • The webserver user has to have permission to write to all areas of your installation for this to work.
• If you have a permanent connection to the internet, you are recommended to use the automatic installer script
  • Just download the FindElsewherePlugin_installer perl script and run it.
• Notes:
  • The installer script will:
    • Automatically resolve dependencies,
    • Copy files into the right places in your local install (even if you have renamed data directories),
    • check in new versions of any installed files that have existing RCS histories files in your existing install (such as topics).
    • If the $TWIKI_PACKAGES environment variable is set to point to a directory, the installer will try to get archives from there. Otherwise it will try to download from twiki.org or cpan.org, as appropriate.
    • (Developers only: the script will look for twikiplugins/FindElsewherePlugin/FindElsewherePlugin.tgz before downloading from TWiki.org)
  • If you don't have a permanent connection, you can still use the automatic installer, by downloading all required TWiki archives to a local directory.
    • Point the environment variable $TWIKI_PACKAGES to this directory, and the installer script will look there first for required TWiki packages.
      • $TWIKI_PACKAGES is actually a path; you can list several directories separated by :
    • If you are behind a firewall that blocks access to CPAN, you can pre-install the required CPAN libraries, as described at http://twiki.org/cgi-bin/view/TWiki/HowToInstallCpanModules
• If you don't want to use the installer script, or have problems on your platform (e.g. you don't have Perl 5.8), then you can still install manually:
  1. Download and unpack one of the .zip or .tgz archives to a temporary directory.
  2. Manually copy the contents across to the relevant places in your TWiki installation.
  3. Check in any installed files that have existing ,v files in your existing install (take care not to lock the files when you check in)
  4. Manually edit LocalSite.cfg to set any configuration variables.
  5. Run configure and enable the module, if it is a plugin.
  6. Repeat from step 1 for any missing dependencies.

Note if you are installing this extension in TWiki version < 4.2, please add these definitions to your Main.WebPreferences, if they are not already there:

• Set SYSTEMWEB = %TWIKIWEB%
• Set USERSWEB = %MAINWEB%

Plugin Info

Plugin Author: TWiki:Main.MikeBarton Version: 15055 (25 Sep 2007) Change History:   25 Sep 2007: TWiki:Main.CrawfordCurrie - Added redirect support, removed illegal calls, and made more efficient 20-Apr-2006: (v1.9) - Now repects <noautolink> ... </noautolink> blocks (Dakar only) and a new NOAUTOLINK preference flag - TWiki:Main.MichaelDaum 07-Apr-2006: (v1.8) - Replaced direct usage of %regex with TWiki::Func::getRegularExpression(), replaced some implicit scalar references with explicit $ notation - TWiki:Main.ScottHunter 08 Apr 2005: (v1.7) - Negated vars DISABLELOOKELSEWHERE and DISABLEPLURALTOSINGULAR can now be set per web (WebPreferences) or per topic. - TWiki:Main.SteffenPoulsen 05 Apr 2005: (v1.6) - Bugfix: Preambles for ACRONYMS were doubled. - TWiki:Main.SteffenPoulsen 04 Apr 2005: (v1.5) - Plugin less greedy - now leaves linktext in [[WikiWord][long links with ACRONYMS or WikiWords]] alone - TWiki:Main.SteffenPoulsen 03 Apr 2005: (v1.4) - Documentation update. - TWiki:Main.SteffenPoulsen 02 Apr 2005: (v1.3) - I18N-support added. New link style. TWiki:Codev.WebNameAsWikiName supported - TWiki:Main.SteffenPoulsen 12-Feb-2004: Matt Wilkie - put all of above into twikiplugins cvs, - removed "/o"'s as there may be issues with modperl (ModPerl) 25-May-2003: Martin Cleaver - patch to add WebNameAsWikiName (cvs rev1.4) 25-Sep-2002: PeterHErnst? - modified webname to show as superscript, - some other changes (chiefly "/o" regex modifiers) (cvs rev1.3) 15-May-2002: Marco Carnut - patch to show webname, e.g. Main (cvs rev1.2) 01 Feb 2002: Initial version License: GPL (GNU General Public License) Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/FindElsewherePlugin Feedback: http://TWiki.org/cgi-bin/view/Plugins/FindElsewherePluginDev Appraisal: http://TWiki.org/cgi-bin/view/Plugins/FindElsewherePluginAppraisal