FindElsewherePlugin < System

You are here: Foswiki>System Web>FindElsewherePlugin (revision 3) (raw view)
---+!! Find Elsewhere Plugin
<!--
   * Set SHORTDESCRIPTION = Automatically link to another web(s) if a topic isn't found in the current web.
-->
%SHORTDESCRIPTION%

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

	* Each web would have to create their own topic for a common term 
	* *Or* would have to link to or INCLUDE the topic from where it is defined
	* *Or* authors would have to remember to put the Web name in front of the topic name, such as [[%SYSTEMWEB%.WikiWord]]

%TOC%

---++ Syntax Rules

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

If a topic or abbreviation is not found in the current web, this plugin will look through the webs listed in the =LOOKELSEWHEREWEBS= preference.  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.

#NewFunctionalityTest

__Single hits__

| *Test case*         | *Input*             | *Output<br/>(if installed)* | *Expected*       |
| Found here          | =<nop>WebHome=        | WebHome        | %SYSTEMWEB%.WebHome     |
| Found singular here | =<nop>WebHomes=       | WebHomes       | [[%SYSTEMWEB%.WebHome][WebHomes]] |
| Found elsewhere     | =<nop>WebSearch= | WebSearch | [[%SYSTEMWEB%.WebSearch][WebSearch]] |
| Found elsewhere (LOOKELSEWHEREFORLOCAL enabled)    | =<nop>%SYSTEMWEB%.WikiUsers= | %SYSTEMWEB%.WikiUsers | [[Main.WikiUsers][WikiUsers]] |
| Found elsewhere (LOOKELSEWHEREFORLOCAL disabled)    | =<nop>%SYSTEMWEB%.WikiUsers= | %SYSTEMWEB%.WikiUsers | [[%SYSTEMWEB%.WikiUsers][WikiUsers]] (non-existing) |
| Found elsewhere     | =[<nop>[AdminGroup][wiki admins]]= | [[AdminGroup][wiki admins]] | [[Main.AdminGroup][wiki admins]] |
| Don't touch direct links     | =[<nop>[%MAINWEB%.AdminGroup][wiki admins]]= | [[%MAINWEB%.AdminGroup][wiki admins]] | [[Main.AdminGroup][wiki admins]] |
| Found singular  elsewhere     | =<nop>WebSearches= | WebSearches | [[%SYSTEMWEB%.WebSearch][WebSearches]] | 
| Found elsewhere, spaced wiki word | =[<nop/>[Web search]]= | [[Web search]] | [[%SYSTEMWEB%.WebSearch][Web search]] |
| Found elsewhere, abbrev | =<nop/>ACRONYM= | ACRONYM | (If <nop/>ACRONYM is a topic defined in one of the LOOKELSEWHERE webs, a link to it should show up) |
| Found elsewhere, abbrev w. alt. linktext | =[<nop/>[ACRONYM][acronym link text]]= | [[ACRONYM][acronym link text]] | (If <nop/>ACRONYM is a topic defined in one of the LOOKELSEWHERE webs, a link to it should show up) |
| Escaped with &lt;noautolink> | =&lt;noautolink> <nop>WebSearch &lt;/noautolink>= | <noautolink> WebSearch </noautolink> | <nop>WebSearch  |

__Multiple hits__

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

	* Standard <nop/>WikiWord: <nop/>DefaultPreferences<sup>([[%SYSTEMWEB%.DefaultPreferences][%SYSTEMWEB%]],[[%USERSWEB%.SitePreferences][%USERSWEB%]])</sup> 
	* [<nop/>[Spaced wiki word]]: <em>Default Preferences</em><sup>([[%SYSTEMWEB%.DefaultPreferences][%SYSTEMWEB%]],[[%USERSWEB%.SitePreferences][%USERSWEB%]])</sup> 

Create this table in [[Sandbox.FindElsewherePluginTest]] to try it out (use raw edit when pasting):

<verbatim>
| *Test case* | *Input* | *Output<br />(if installed)* | *Expected* |
| Found elsewhere, spaced wiki word | [<nop>[Default Preferences]] | [[Default Preferences]] | %SYSTEMWEB%.DefaultPreferences |
| Found elsewhere | <nop>ProjectContributor | ProjectContributor | <nop>ProjectContributor<sup>([[%SYSTEMWEB%.ProjectContributor][%SYSTEMWEB%]],[[%MAINWEB%.ProjectContributor][%MAINWEB%]])</sup> |
</verbatim>

__Internationalization__

<nop/>FindElsewherePlugin handles international characters (I18N) in links, topics and webs.

__Compatibility__

| *Input*								 | *Output*				  |
| <nop>%TOPIC%#TopicAnchor		  | %TOPIC%#NewFunctionalityTest  |
| <nop>%SYSTEMWEB%.WebHome			| %SYSTEMWEB%.WebHome	 |
| <nop>WebHome						  | WebHome					|
| [<nop>[%SYSTEMWEB%.WebHome]]	  | [[%SYSTEMWEB%.WebHome]]	  |
| [<nop>[%SYSTEMWEB%.WikiWord]]	 | [[%SYSTEMWEB%.WikiWord]]	 |
| [<nop>[%SYSTEMWEB%.WikiWords]]	| [[%SYSTEMWEB%.WikiWords]]	|
| <nop>%SYSTEMWEB%.WikiWord		  | %SYSTEMWEB%.WikiWord	|
| <nop>%SYSTEMWEB%.WikiWords		 | %SYSTEMWEB%.WikiWords  |
| [<nop/>[%MAINWEB%.WebSearch][This is a link to <nop/>WebSearch in <nop/>%MAINWEB%]] | [[%MAINWEB%.WebSearch][This is a link to WebSearch in %MAINWEB%]] |

---++ <nop>%TOPIC% Settings

---+++ Enabling and disabling the plugin globally

You can enable or disable the <nop>%TOPIC% plugin sitewide (in %USERSWEB%.SitePreferences), per web (in <nop/>WebPreferences) or per topic by defining DISABLELOOKELSEWHERE = 1.

---+++ Where it looks to find topics

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, =System,Main=

---+++ Singular and plural topics

If the %SYSTEMWEB%.WikiWord is plural but doesn't exist, %TOPIC% 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, dependent on the setting in =configure=).

---+++ <nop>ACRONYM link preference

The =LOOKELSEWHEREFORACRONYMS= preference can be set to a value of =none=, =first= or =all= (=all= is default). 

=none= means that non-forced acronyms in topics are never found elsewhere, =first= that they are linked only at the first occurence and =all= that every occurence is linked. Especially topics with many occurences of the same acronym will experience improved readability by use of the =first= setting.

---+++ Overriding forced local links

Even if a link refers explicitly to the current web and a topic name (for
example, [<nop>[Thatweb.ThatTopic]], you can still trigger
%TOPIC% 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.

Enabled for demo and testing - try it on and off

   * Set LOOKELSEWHEREFORLOCAL = 1

---++ <nop>%TOPIC% Hints

	* You can en- or disable this plugin for webs, topics or users, using the standard Foswiki preferences hierarchy
	* You can avoid single words being looked up by using =!DontLookup= or =&lt;nop/&gt;DontLookup= syntax
	* "Groups of webs" can use each other as lookup webs, by setting the =LOOKELSEWHEREWEBS= preference accordingly in their !WebPreferences

---++ Pre Dakar TWiki linking
Before Hierarchical or Nested webs were added to TWiki in 2005, topic linking rules were a little more relaxed. 
If you are upgrading with content that is this old, you may find some =[<nop>[square backet]]= links don't work any more.

You can fix this by setting the ={FindElsewherePlugin}{CairoLegacyLinking}= setting in =configure= to true.

this will link
<verbatim>
   * [[Arth's Checklist]] to ArthsChecklist
   * [[MyNNA bugs/feature requests]] to MyNNABugsfeatureRequests
   * [[6to4.enro.net]] to 6to4enronet
</verbatim>

_Alternativly_ you can disable Hierarchical webs and add the forward Slash to the ={NameFilter}= in =configure=

<verbatim>
$Foswiki::cfg{EnableHierarchicalWebs} = 0;
$Foswiki::cfg{NameFilter} = $Foswiki::cfg{NameFilter} = '[\/\\s\\*?~^\\$@%`"\'&;|<>\\[\\]#\\x00-\\x1f]';
</verbatim>
---++ 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.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in =configure=, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.


---++ Info

|  Author: | Mike Barton |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  Version: | 14641 (2012-04-19) |
|  Release: | 2.4 |
|  19 Apr 2012: | (v2.4)  Foswikitask:Item11778: FindElsewherePlugin breaks other plugins, prevents jquery.json.js from loading. |
|  26 Mar 2012: | (v2.3) Foswiki:Main.SvenDowideit - Foswikitask:Item11695: add pre-Dakar linking |
|  16 Nov 2011: | (v2.2) Foswiki:Main.GeorgeClark - Foswikitask:Item10460 - expand macros in web list, Foswikitask:Item11199 - Don't autolink wikiwords that are part of an email address. Added unit tests and addressed possible reusability issues under fastcgi or mod_perl.  Replace deprecated =startRenderingHandler= with =preRenderingHandler=. |
|  10 Jun 2010: | (v2.1) Foswiki:Main.CrawfordCurrie - major tidy-up, including removal of NOAUTOLINK no-op |
|  25 Mar 2009: | (v2.0.1) Foswiki:Main.KennethLavrsen - fixed so it does not remove square bracket links to non-existing topics. Example in plugin topic fixed |
|  16 Dec 2008: | (v2.0.0) Foswiki:Main.KennethLavrsen - rebranded to Foswiki |
|  19 Dec 2007: | Steffen Poulsen - Link none, first or all standalone abbreviations (LOOKELSEWHEREFORACRONYMS option added) |
|  18 Dec 2007: | Steffen Poulsen - Abbrev with alternative linktext found elsewhere again |
|  25 Sep 2007: | Crawford Currie - Added redirect support, removed illegal calls, and made more efficient |
|  20-Apr-2006: | (v1.9) - Now respects &lt;noautolink&gt; ... &lt;/noautolink&gt; blocks and a new NOAUTOLINK preference flag - Michael Daum |
|  07-Apr-2006: | (v1.8) - Replaced direct usage of %regex with :Func::getRegularExpression(), replaced some implicit scalar references with explicit $ notation - Scott Hunter |
|  08 Apr 2005: | (v1.7) - Negated vars =DISABLELOOKELSEWHERE= and =DISABLEPLURALTOSINGULAR= can now be set per web (!WebPreferences) or per topic. - Steffen Poulsen |
|  05 Apr 2005: | (v1.6) - Bugfix: Preambles for ACRONYMS were doubled. - Steffen Poulsen |
|  04 Apr 2005: | (v1.5) - Plugin less greedy - now leaves linktext in [<nop/>[WikiWord][long links with <nop/>ACRONYMS or <nop/>WikiWords]] alone - Steffen Poulsen |
|  03 Apr 2005: | (v1.4) - Documentation update. - Steffen Poulsen |
|  02 Apr 2005: | (v1.3) - I18N-support added. New link style. Codev.WebNameAsWikiName supported - Steffen Poulsen |
|  12-Feb-2004: |	Matt Wilkie - put all of above into twikiplugins cvs, - removed "/o"'s as there may be issues with modperl  |
|  25-May-2003:	| Martin Cleaver - patch to add !WebNameAsWikiName |
|  25-Sep-2002:	| PeterHErnst - modified webname to show as superscript, - some other changes (chiefly "/o" regex modifiers) |
|  15-May-2002:	| Marco Carnut - patch to show webname, e.g. Main.<nop>WebHome |
|  01 Feb 2002: | Initial version |
|  Home: | http://foswiki.org/Extensions/%TOPIC% |
|  Support: | http://foswiki.org/Support/%TOPIC% |
Toolbox

User Reference

Admin Maintenance

Categories
