Template:Tooltip poe2/doc

Displays a fancy Deadfire-themed tooltip capable of displaying any wiki-formed content (text, images, html, etc). The tooltip has a maximum width of 350px.

The tooltip is removed from the standard layout flow, and is drawn on top of all other elements. The CSS used to style this tooltip is contained in MediaWiki:Hydradark.css, under the classes "advanced-tooltip" and "poe2-tooltip". In order to programatically transition the tooltip (with individually-controllable delays, durations, conditions, etc), CSS psuedo-selectors and transitions are not used in favor of jQuery animations and CSS manipulation. The JavaScript used to control this (and to tidy things up a bit) can be found in MediaWiki:Tooltip.js, with a load statement at the top of MediaWiki:Hydradark.js. This means that disabling JavaScript will effectively disable these tooltips.

While this tooltip uses jQuery, it does not use built-in jQuery UI tooltips (despite this library being present on most MediaWiki installs).

This template is not displayed on mobile, but IS parsed.

Todo

 * Abstract this template into two separate "functional" and "style/content" templates to allow for different styles of tooltip in the future without having to duplicate the entire template. In this way, you'd have one template handle all the functional jQuery stuff, and another used to actually display the tooltip. You'd simply call the latter and pass whatever you need to it. More technical parameters could be passed through optionally, or can be predefined. Could do this either with transclusion and parameter passthroughs, or template nesting.
 * Allow dynamically sized container and content.

Example 1
Results in:

Example 2
{{Tooltip poe2|Form of the Helpless Beast|Transforms a single kith enemy (aumaua, dwarf, elf, godlike, human, or orlan) into a pig. The pig has very poor defenses but can move quickly. }}
 * icon = form_of_the_helpless_beast_icon.png
 * title = Form of the Helpless Beast}
 * mode = stay

Results in:

Parameters
All parameters are optional. Most parameters are named using hyphens (instead of camel case) to make them similar to the data attributes they are used in.

Tooltip container and contents

 * or container
 * Content to display normally. When hovered over, the tooltip will be shown.


 * Ensure that all equals ('=') signs are escaped when passed within an anonymous/unnamed parameter, otherwise they will be treated as a named parameter separator. You can do so by using Template:= or  (the latter only in wikitext). This issue may be encountered in text, or more commonly when declaring attributes in HTML passed to the template. Alternatively you can use a named parameter   instead, which forgoes the need to escape anything. Typically this would require that you use all named parameters (to prevent other anonymous parameters from being offset), but the template handles this automatically so there is no need.


 * or content or tooltip
 * Contents of tooltip, can be any wikitext.


 * icon
 * Name of icon to display in the header, typically an item or ability icon of 42x42px. If larger, the image will be scaled down to fit in this area. If both  and   are omitted, a header will not be shown.


 * title
 * Header text to display. Can be wiki-formed, but should ideally not contain any non-text content. The title box is limited to 200px (for styling purposes), after which it will wrap the text to a new line. Links are styled with the regular wiki skin colours.


 * link
 * Name of page to go to when the icon is clicked. Note that the mode must be set to  or   for the tooltip to remain navigable. If not present, the icon links to nothing.


 * style
 * A style to apply to the topmost container class. By default only two properties are set:, and changing these might have negative effects.

Positioning and display
Offsets and anchors are only calculated once (for performance reasons). If the size of your content changes dynamically and you use percentage based offsets, or anchors - don't expect everything to work perfectly!

If no positioning parameters are present (i.e. anchors or offsets), the tooltip will default to  and   (the tooltip is shown above the container). If any positioning parameters are present, the tooltip will start at 0,0, an equivalent of  and.

Four different modes are available:
 * mode
 *   - Default mode, tooltip disappears immediately when the cursor leaves the hover area.
 * - The tooltip is navigable (allowing the user to click links, copy text, etc), and only disappears if the cursor leaves the tooltip area. Keep in mind using this mode can obscure content under the tooltip, and will use pointer events which can make it annoying for users.
 * - The tooltip is always displayed.
 * - The tooltip is never displayed.

Note that you should not use  in conjunction with   (or the macro  ), since it will cause the tooltip to remain open permanently (or at least for as long as the browser can keep up).


 * show-delay
 * The amount of time (in seconds, without unit) to wait before showing the tooltip after the cursor enters the container. The delay is reset if the mouse cursor leaves the container. Default is 0 (no delay)


 * hide-delay
 * The amount of time (in seconds, without unit) to wait before hiding the tooltip after the cursor leaves the container. The delay is reset if the mouse cursor enters the container. Default is 0 (no delay).


 * Use this if you want to have your tooltip linger before disappearing, which might be useful in conjunction with mode=stay to give the user more time to cursor over the tooltip.


 * fade-in-time
 * Duration of fade in (in seconds, without unit). Default is 0.15
 * The duration is adjusted based on the current opacity. For example if the opacity at mouse enter is 0.5 and the fade in duration is 2, it will take 1 second to fade to an opacity of 1. This is typically not the case.


 * fade-out-time
 * Duration of fade out (in seconds, without unit). Default is 0.05, pretty much instant.
 * The duration is adjusted based on the current opacity. For example if the opacity at mouse exit is 0.5 and the fade out duration is 2, it will take 1 second to fade to an opacity of 0. This is typically not the case.

Shortcut to set container-offset and local-offset to preset values. container-anchor is always the starting position of the tooltip on the container, while local-anchor is which corner of the tooltip to place on the starting position (top-left being the default). Keep in mind that local anchors are inverted (the values in the table below are made negative).
 * container-anchor / local-anchor

You may use both anchors and offsets in the same tooltip, though it is not recommended for clarity (generally you should use one or the other). If both values are present, they will be added together. For example using  with   will place your tooltip on the right edge of the container, then offset it by half of the container's width. Using  and   will place your tooltip in the center of the container-anchor/offset, plus 50px downwards.

Shortcut/macro to set container-anchor and local-anchor to a set of commonly used values, so that the tooltip will appear on the side of the container specified (e.g. anchor=top-left will place the tooltip to the top left of the container. Note that using "anchor" will set different values for container-anchor and local-anchor (typically the inverse).
 * anchor

If anchor is set, you should NOT use container-anchor or local-anchor. If these parameters are present, they will be ignored. Offsets may still be used.

Valid values are:


 * container-offset-x and container-offset-y
 * Defines the offset of the tooltip relative to the container (where 0,0 is the top left of the container).


 * Can use either pixel units (by adding a "px" suffix, optionally), or a percentage value (by adding a "%" suffix). If a percentage is used, the value will be in the context of the container width/height, where x=100% is the width of the container and y=100% is the height. Positive values shift the offset right/down, and negative values shift the offset left/up.


 * local-offset-x and local-offset-y
 * Defines the offset of the tooltip relative to the container-offset (the "anchor", starting position). By default, an offset of 0,0 places the top-left corner of the tooltip on the anchor point, so that the tooltip content is to the bottom right of the anchor.


 * Can use either pixel units (by adding a "px" suffix, in which case it has the same effect as container-offset), or a percentage value (by adding a "%" suffix). If a percentage is used, the value will be in the context of the tooltip width/height, where x=100% is the x width of the tooltip and y=100% is the height. Positive values shift the offset right/down, and negative values shift the offset left/up.

Used to update the x/y position of the tooltip to match the cursor position on the update event, with the offsets, anchors and update-event values taken into consideration. Valid values are: Default is unassigned (do not follow cursor)
 * follow-cursor
 * - x axis only
 * - y axis only
 * - both x and y axes. When using mousemove, the container-offset and container-anchor values become irrelevant as the tooltip is instead anchored to the cursor.
 * - both x and y axes, but also set  to   overriding any other value set for it.

If set, the script will keep the tooltip within the viewport (browser window). Three different modes are available:
 * clamp-viewport
 * - (Default) Does not clamp the tooltip to the viewport.
 * - If the tooltip is outside the viewport, the tooltip will be pushed back so that it is within view. This is best used when follow-cursor is enabled. Note that this may cause the tooltip to obscure the container when pushed back.
 * - Inverts the container offset, shifting the anchor to the opposite axis. The position is pushed back first, and then inverted if the tooltip is within the container. For example if the tooltip cannot fit below the container, it is shifted to above the container. Best used when the tooltip is drawn on the outside of the container and needs to never obscure the container. Using this with an interior placement may yield strange results.
 * - Inverts the local offset, shifting the anchor to the opposite axis. This effectively inverts the tooltip.

The clamped position is only calculated on the update event, meaning if the user scrolls the tooltip off the screen and maintains hover, the tooltip will not be redrawn in a clamped position.

Clamping will only occur once, and in the following order: top -> bottom -> left -> right. This means if the resulting clamped position is still out-of-bounds, then it will not be fixed a second time (if this is the case, the window is probably too small to fit the tooltip anyway)


 * clamp-viewport-axes
 * Limit viewport clamping to a specific axis. Valid values are,  , and  . Default is   if clamp-viewport is used.

Determines when the tooltip's position should be updated, and can be any event string.
 * update-event


 * Default is.
 * If you want to update the position on mouse move, use, and ensure you combine it with a   value (otherwise it will have no effect).
 * If you use a non mouse event, yet have the tooltip following the cursor, another "proxy" event will be set up to capture the mouse position.

This hasn't been tested thoroughly.

Images
The following images are used in the tooltip markup.