Extension:TippingOver/Configuration settings

Configuration concepts
TippingOver does have a lot of configuration settings and configuration may be quite complex in certain cases. But many of the settings are performance tweaks for users using more advanced setups. Many use cases work just fine with default settings, and other common use cases only require a few setting changes.

Settings that may be of interest for simple use cases include: See below for more information on these settings.

Helpful terminology
Some quick TippingOver terminology to help clarify the following setting descriptions:
 * Link
 * Any portion of page content which TippingOver considers attaching a tooltip to. This may be actual internal links to other pages on the wiki or any content contained within a #tipfor call.


 * Target
 * For internal links, the target is the page they link to. In other words, where the wiki takes you when you follow the link. In #tipfor calls, the target page is the page title passed as the first parameter.


 * Early
 * "Early" steps are actions TippingOver performs before a page is even viewed. These will generally happen when a page is saved and any other time the wiki needs to regenerate the page from its wikicode, such as perhaps a template the page uses being edited. Performing actions early has the advantage of avoiding doing the work for each user every time they hover over a link, but in some use cases, might unacceptably degrade the speed of page  regeneration resulting in slow loads or even timeouts.


 * Late
 * "Late" steps are actions TippingOver waits to perform until the user actually hovers over the link with the mouse. This is also commonly referred to as "lazy", such as in "lazy load." This has the advantage of saving these steps until they need to be performed, which also ensures they are performed with current information, but it can slow tooltip loads, since more must be done on mouse-over, and means the work will have to be repeated for every user.

Process overview for attaching and showing tooltips
For configuration, it also helps to have an overview of TippingOver's process for attaching and showing tooltips:
 * First, a namespace check is performed on the current page. If it's outside an enabled namespace (see ), TippingOver will stop doing anything on that page.
 * Second, optionally, an lookup index is built for the category filter. (See .)
 * Then, for each link during the early stage, the following steps are performed except when disabled (see  for including or excluding image links):
 * Target page namespace check. See.
 * Early target redirect follow. See.
 * Early category filtering. See,  , and.
 * Early page title parse. See  and.
 * Early exists check. See.
 * If no early checks prevent it, a tooltip is attached.
 * Finally, for each link that has a tooltip attachment, the following steps, if enabled or not completed early, happen when the user mouses over the link:
 * Possibly show a loading tooltip now. See.
 * Late target redirect follow. See.
 * Late category filtering. See.
 * Late page title parse. See  and.
 * Late exists check. See.
 * Possibly show a loading tooltip now if not up already. See  and.
 * Actually load the tooltip. See  and v$wgEmptyPageNameTooltip for alternatives when there's no tooltip to load.

Settings below are listed in the order in which they become relevant to the above process.

Configuration settings
At present, editors must send a request to their wiki manager to change any of the following settings.

This defines what namespaces tooltips are actually displayed in. When viewing pages in namespaces where this is set to, no internal links on the page will display tooltips. // Default $wgtoEnableInNamespaces = Array( NS_MAIN => true,                                NS_TALK => false,                                 NS_USER => true,                                 NS_USER_TALK => false,                                 NS_PROJECT => true,                                 NS_PROJECT_TALK => false,                                 NS_IMAGE => false,                                 NS_IMAGE_TALK => false,                                 NS_MEDIAWIKI => false,                                 NS_MEDIAWIKI_TALK => false,                                 NS_TEMPLATE => false,                                 NS_TEMPLATE_TALK => false,                                 NS_HELP => false,                                 NS_HELP_TALK => false,                                 NS_CATEGORY => true,                                 NS_CATEGORY_TALK => false,                               );

This defines how TippingOver should perform early category filtering if it is enabled in. This setting is just for performance tweaking and can likely be left alone if the wiki doesn't appear to be suffering from performance issues. Valid values are: If both options seem to be dragging down the wiki, consider disabling  and check out   instead. // Default $wgtoPreprocessCategoryFilter = true;

This defines whether or not tooltips are enabled on image links. In most cases, this refers to links that would be created by something like. It can even be possible, in certain configurations, for the images themselves to have tooltips, so even a link like  could potentially show a tooltip if this is enabled. Valid values are: // Default $wgtoEnableOnImageLinks = true;

This defines which internal links to which namespaces will have tooltips enabled Links to pages in namespaces where this is set to , or which do not appear in the array, will not have tooltips displayed. // Default $wgtoNamespacesWithTooltips = Array( NS_MAIN => true,                                    NS_TALK => false,                                     NS_USER => true,                                     NS_USER_TALK => false,                                     NS_PROJECT => false,                                     NS_PROJECT_TALK => false,                                     NS_IMAGE => false,                                     NS_IMAGE_TALK => false,                                     NS_MEDIAWIKI => false,                                     NS_MEDIAWIKI_TALK => false,                                     NS_TEMPLATE => false,                                     NS_TEMPLATE_TALK => false,                                     NS_HELP => false,                                     NS_HELP_TALK => false,                                     NS_CATEGORY => false,                                     NS_CATEGORY_TALK => false, );

This defines whether TippingOver follows redirects in link or  targets before early category filtering and early page title parsing. Valid values are: // Default $wgtoEarlyTargetRedirectFollow = true;

This defines if the target page of links should be checked to see if they are in the hierarchy of a tooltip-enabling or disabling category when the links are generated.

Valid values are: // Default $wgtoEarlyCategoryFiltering = false;

Only applies if  and/or   are set to. When those settings are applied, a link only gets a tooltip when its target page is in the category defined by this setting or one of its subcategories. The Category: namespace is optional when defining the category in this setting.

Setting this to  or an empty value will cause category filtering to use the disabling category in   instead. In the current version, only one or the other operates at any given time, but a future version may allow both to function simultaneously. // Default $wgtoEnablingCategory = "Has tooltips enabled";

Only applies if  and/or   are set to   and   is set to   or an empty value. When those settings are applied, a link will not get a tooltip when its target page is in the category defined by this setting or one of its subcategories. The Category: namespace is optional when defining the category in this setting. But pages outside that category hierarchy do; it functions exactly opposite of.

In the current version, if there is an enabling category, the disabling category won't be used. In a future version, however, they may be set up to work together as follows: links would have their tooltips disabled if either the target page was in the disabling category hierarchy somewhere or not in the enabling category hierarchy somewhere. In other words, the disabling category will have priority when a target page is in both hierarchies. // Default $wgtoDisablingCategory = "Has tooltips disabled";

This defines if the title of the targets of a page's links should be sent to MediaWiki:To-tooltip-page-name to find the values whenever the page is recached on the server side. Valid values are: // Default $wgtoEarlyPageTitleParse = true;

This determines if TippingOver should assume MediaWiki:To-tooltip-page-name will always return a page name. Valid values are: // Default $wgtoAssumeNonemptyPageTitle = false;

This defines whether or not a check is made that the page identified by processing MediaWiki:To-tooltip-page-name exists for the given target page of a link during an early page title parse. Valid values are: // Default $wgtoEarlyExistsCheck = true;

This defines what page, if any, to use as a loading tooltip. In other words, this is what will be displayed while the actual tooltip for the page is being requested from the server. To disable loading tooltips completely, set this to   or an empty value. The loading tooltip is displayed while waiting for the server to return the requested tooltip after a user hovers over a link. This can also be disabled by blanking or deleting the page in question, though this is slightly less efficient as there is more overhead involved in checking that, but it does allow it to be enabled more easily later on.

Important note: In some situations, the loading tooltip may be automatically disabled. This occurs in some cases when various early checks are disabled, leaving TippingOver in a situation where it doesn't yet know whether there is a tooltip to show. Rather than show a loading tooltip and then nothing, it just tries to load the tooltip instead. This behavior can be changed by setting  to , but this isn't recommended. See  below for more information. // Default $wgtoLoadingTooltip = "MediaWiki:To-loading-tooltip";

This defines whether TippingOver follows redirects in link or  targets when the user mouses over a link with the tooltip attached.

Important note: This only applies to links to which no early target redirect following, no early category filtering, no early page title parse, and no early exists check has been applied. Any of those steps being completed on a link causes this step to be bypassed for that link, regardless of the setting. Valid values are: // Default $wgtoLateTargetRedirectFollow = true;

This defines if the target page of links should be checked to see if they are in the hierarchy of a tooltip-enabling or disabling category when the user hovers over the links. Valid values are: // Default $wgtoLateCategoryFiltering = false;

This defines if the title of the targets of a page's links should be sent to MediaWiki:To-tooltip-page-name in a request send when the user hovers their mouse over links. Valid values are: // Default $wgtoLatePageTitleParse = true;

This defines whether or not a check is made that the page identified by processing MediaWiki:To-tooltip-page-name exists for the given target page of a link during an late page title parse triggered by the user hovering their mouse over a link. Valid values are: // Default $wgtoLateExistsCheck = true;

The "two request process" is where TippingOver makes one request to the server just to determine if there is a tooltip, and then if there is, another request to actually load it.

If allowed by this setting, TippingOver will only use this process if a loading tooltip exists and any of these configurations are specified: When disallowed, TippingOver quietly and automatically disables the loading tooltip instead and just proceeds with a single request to fully load the tooltip (or quietly stop if there's nothing to show).
 * is  and   is   with no valid empty page name tooltip unless   is set to   (but see risks with that setting),
 * is  and   is true with no valid missing page tooltip unless $wgtoEarlyExistsCheck and $wgtoLateExistsCheck are both false (but see risks with that situation),
 * is  and   is   with no valid missing page tooltip, or
 * is  and   is   under any circumstance.

Disallowing the two request process is default, as permitting it is not recommended. It takes approximately twice as long to load a tooltip this way, and showing the loading tooltip is delayed because TippingOver will wait for the response to the first request so it doesn't show the loading tooltip when there will be no tooltip to show. (The single exception is explained with the $wgtoAssumeNonemptyPageTitle setting description.) But if showing a loading tooltip is strongly desired even in the above configurations, this process is available.

Valid values are: // Default $wgtoAllowTwoRequestProcess = false;

This defines what page, if any, to use as a tooltip if the page identified by processing MediaWiki:To-tooltip-page-name doesn't exist. To disable this entirely, set this to  or an empty value. This can also be disabled by blanking or deleting the page in question, though this is slightly less efficient as there is more overhead involved in checking that, but it does allow it to be enabled more easily later on. Warning: See warning under  below before disabling this in any way. // Default $wgtoMissingPageTooltip = "MediaWiki:To-missing-page-tooltip";

This defines what page, if any, to use as a tooltip if processing MediaWiki:To-tooltip-page-name results in an empty value being returned. To disable this entirely, set this to  or an empty value. This can also be disabled by blanking or deleting the page in question, though this is slightly less efficient as there is more overhead involved in checking that, but it does allow it to be enabled more easily later on. Warning: See warning under  below before disabling this in any way. // Default $wgtoEmptyPageNameTooltip = "MediaWiki:To-empty-page-name-tooltip";