Help:TippingOver/Customizing tooltip page titles

TippingOver uses MediaWiki:To-tooltip-page-name to figure out what page should be the tooltip for the target page of a given link.

The process of determining a tooltip page title
When TippingOver needs to determine the title of a tooltip page for a given link, it goes through the following steps:
 * 1) It retrieves the wikitext of MediaWiki:To-tooltip-page-name if it hasn't already.
 * 2) It performs a series of token replacements within that text.
 * 3) *  is replaced with the page title of the link target, unless the link target is a redirect when redirect following is enabled, in which case it is replaced with the page title it redirects to.
 * 4) ** If, for example, the link were to the page Example,  would be replaced with   if it is not a redirect or if redirect followed is disabled.
 * 5) ** If it were a redirect, say to Example2, then  would be replaced with   instead.
 * 6) *  is replaced with any anchor targeted in the link, unless the link target is a redirect when redirect following is enabled, in which case it is replaced any anchor text in the redirect target.
 * 7) ** If, for example, the link were to the page Example#Heading1,  would be replaced with   if it is not a redirect or if redirect followed is disabled.
 * 8) ** If it were a redirect, say to Example2#Heading2, then  would be replaced with   instead.
 * 9) *  is replaced with the page title of the link target whether or not that target is a redirect.
 * 10) *  is replaced with any anchor targeted in the link whether or not the linked page is a redirect.
 * 11) After the replacement, the wikitext is run, so parser functions and tags from both MediaWiki core and any other installed extensions can be used.

Note that this means MediaWiki:To-tooltip-page-name is effectively useless without one of the special tokens (, ,  , or  ) since this would simply cause it to always return the same value. Also note that editing this does not automatically move any existing tooltip pages; this will have to be done manually.

Default behavior: using subpages
By default, the content of MediaWiki:To-tooltip-page-name is: $1/Tooltip

For a link to the page Example,  is replaced with "Example", making the tooltip page Example/Tooltip.

Using a custom namespace for tooltips
One example of a potentially desirable change would be to use a custom namespace for tooltip pages rather than making them subpages. Setting up custom namespaces is discussed on this MediaWiki manual page.

Assuming that a namespace named "Tooltip" has been properly set up on a wiki, editing MediaWiki:To-tooltip-page-name to have TippingOver use pages in that namespace is simple: Tooltip:$1

With that, the tooltip page for a page named Example is now Tooltip:Example.

Using images for tooltips
As noted when detailing a configuration for using images as tooltips, editing MediaWiki:To-tooltip-page-name and changing it to: File:$1 tooltip.png

would change the tooltip for links to Example to File:Example tooltip.png.

Advanced cases
For most situations, simple logic like the above cases is probably perfectly adequate. As noted above, though, the contents of MediaWiki:To-tooltip-page-name are processed as wikitext after the tokens are replaced, allowing any appropriate tags, parser functions, or magic words to be used in generating the appropriate title for the tooltip page.

Using a different tooltip title when the link includes an anchor
An anchor (text after a  that targets an anchor on a page, usually a heading) can be used in generating tooltip page names. For example: $1/Tooltip

would change the tooltip for links to Example to Example/Tooltip, but for a link to Example#Heading, the tooltip would be at Example.Heading/Tooltip.

Using the namespace of a target page to change how a title is generated
Let's say the admins of a particular wiki have set up a "Tooltip" namespace, and they want to allow users to set up tooltips within the User namespace as well so user-specific tooltips aren't ending up in the same namespace as tooltips for regular content.

One way to accomplish this would be to use the  function from the common ParserFunctions extension and the built in   magic word like this:

In this case, the tooltip page for a link to Example will be Tooltip:Example, but a link to User:Example will be User:Example/Tooltip.

Special redirect handling
On links to redirects, it may sometimes be desirable to check if the redirect page has a tooltip before using the tooltip of the redirect's target page. One possibility would be to use something like this:

Unfortunately, this example uses the expensive parser function  from the ParserFunctions extension. See the notes below for drawbacks to doing so.

Returning empty values
In some cases, it may be useful for MediaWiki:To-tooltip-page-name to return empty values occasionally to indicate that no tooltip should be shown. Let's say that on a given wiki, the admins have decided that subpages should never have a tooltip of their own. This would be one way to accomplish this:

In this case, any subpage, such as Example/Subpage won't pass the equality check and an empty value will be returned. What TippingOver does in this situation will depend on the configuration and if there is a valid empty page name tooltip available. Under the default configuration, it will show MediaWiki:To-empty-page-name-tooltip if it has any contents; if not, it assumes an empty value means the link should not have a tooltip. For example, in this case, if the configuration is default and MediaWiki:To-empty-page-name-tooltip is empty, TippingOver will not show tooltips on links to any subpage.

Using ifexist
Keep in mind that, by default, TippingOver already performs a check to see if a tooltip page exists during the page load. In most cases, using the  function would simply double up the checks and might impact performance when saving link-heavy pages. If  is required, consider asking your wiki manager to set both   and   to false to disable TippingOver's own check.

It is also important to note that the number of uses of  is limited as per any other parser function considered to be "expensive," so the following advice should be considered before relying on it.

Performance implications
The examples shown above can all be processed very quickly and should have negligible impact on page saving times, not counting other tasks TippingOver may perform during a page save. But sometimes it will be desirable to use expensive functions such as, the   function from Cargo, the   function from DynamicPageList3, or others not included here that aren't quite so quick. Individually, these don't have a lot of impact, but TippingOver could be running MediaWiki:To-tooltip-page-name for every link on a page, and the time required to process these functions can add up quickly. This could lead to very slow page saving times (and the occasional slow page load), or even worse, timeouts where nothing but a blank page appears. This will affect link-heavy pages more severely.

Using late page title parsing
If expensive or potential slow functions are needed, one way to eliminate or greatly reduce the danger of slow loads or timeouts is to reconfigure TippingOver to determine tooltip page titles when a user hovers over a link rather than when the page is saved or recached. This is done by asking your wiki manager to set  to   and   to   (if it isn't already).

This has the following advantages:
 * MediaWiki:To-tooltip-page-name is only parsed when a user actually hovers over a link, so chances are low that it will actually be parsed for every link on a page.
 * Each is parsed in its own request, so the chance of timeout is basically zero unless MediaWiki:To-tooltip-page-name is astronomically complicated, and running into limits on the use of expensive parser functions becomes very unlikely.

But there are tradeoffs:
 * The built-in check to determine if a tooltip page exists can't run during the page save because TippingOver will not know what title to check at that time. It will either have to be done in MediaWiki:To-tooltip-page-name with  and   both set to ,  or delayed by setting   to   and   both set to.
 * TippingOver won't be able to disable tooltips on links with missing pages, or show the missing page tooltip, until after the user hovers over the link and the server responds. There will be a loading delay on these like any other tooltip, though it will be invisible if there is no missing page tooltip to show.
 * Loading tooltips might be suppressed as explained below.

Configurations where loading tooltips are suppressed
Loading tooltips will be suppressed in certain configurations that create situations where TippingOver will not assume there is anything to show when hovering over a link that potentially has a tooltip, thus avoiding the situation of showing the loading tooltip for it to simply disappear. The following configurations where this will happen are listed below.

The suppression of loading tooltips in the above configurations can also be avoided by having  set to. Instead of suppressing the loading tooltip, TippingOver makes a separate request to the server to check if there is anything to show or not. It then displays the loading tooltip if it receives a response indicating there is something to show, and then makes its request for the content it needs to show. Allowing the two-request process is disabled by default since it is inefficient and simply forgoing a loading tooltip is recommended where using the above configurations is desirable.