ReferencePopups

Scope
 Author(s)
 Code

*原始來源︰http://dev.wikia.com/wiki/ReferencePopups*

This is a reimplementation of Wikipedia's reference popup gadget; a feature which allows you to hover over a citation and view the contents of the reference in a floating box. The obvious advantage of this is that you can view the references in situ (in position), without having to scroll to the bottom or click the citation and lose your place in the article. You can have a look at the demonstration here.

This gadget includes intelligent color scheme matching so it will try to fit itself into the wiki's color scheme automatically without requiring any custom CSS to fix it. It does this using the colors from Special:ThemeDesigner; if you have altered the wiki's colors using CSS instead of ThemeDesigner then this might not work properly.

Monobook lacks ThemeDesigner support which means that the color system for that skin is more fragile than Oasis, so please be sure to check that it displays appropriate colors in that skin when you install it. If you encounter a wiki where the color adaptation doesn't work properly and it looks wrong, please report it on the talk page so that it can be made smarter.

## Installation

Add the appropriate row to your `importArticles` in MediaWiki:Common.js:

```
importArticles({
 type: 'script',
 articles: [
 // ...
 'w:c:dev:ReferencePopups/code.js',
 // ...
 ]
});

```

## Usage Notes

The popups are configurable via the built-in UI. You can trigger them via clicking instead of hovering, customise the hover delay, and turn the animations on and off. It's also possible to disable them entirely on a per user basis for individual users who don't want it.

When popups are disabled, there is a link at the end of the article, just below the categories, that can be clicked to reopen the configuration UI to turn them back on later.

### Quick Help on Configuration

The options in the popup configuration are:

* **Disable Reference Popups** — This deactivates the popups so they will no longer appear, except custom ones. They can be turned back on using the "Configure Reference Popups" link at the bottom of articles.
	+ Some wikis may lock the popups which will prevent you from being able to turn them off. You should contact the administrators on that wiki to discuss it in that case.
* **Hover delay** — The amount of time (in milliseconds) you must hover your mouse over the reference before the popup will open. The default is 200ms but you can adjust it if this is too long or too short for your taste. Be aware that very short values can be annoying when scrolling.
* **Make popups stay open until touched with the mouse** — Popups will stay open once they appear, like they do in Click mode, until you move your mouse over the popup and then out of it. This allows you to open the popup by hovering then move your mouse somewhere else without the popup closing on you until you want it to.
* **Activate by** — By default, the popups react on hovering; however, you can toggle between hovering and clicking at your preference. In click mode, you must click the references to open the popups.
	+ In click mode, clicking the reference a second time whilst the popup is already open will bypass it (close it) and take you to the references section at the bottom of the article as per normal.
* **Enable Open/Close Animations** — By default, the popups have a sliding open/closed animation that runs for 300ms. This is generally more pleasing to the eye then snapping open, but if you don't care for it then you can turn it off.

## Administrator Configuration

Administrators can remove the gadget's configuration link from their wiki by putting Reference Popups into "lockdown" mode. This will force the popups to stay enabled and remove the configuration link from the end of the article, but not from the popup itself.

To enable lockdown, just add this to MediaWiki:Common.js **above** the aforementioned import:

```

```

You can also alter the defaults for new users. You can disable the animation by default using:

```

```

## Custom Popups

The popup component of this script is fully reusable and can repurposed to display anything you want as well as references. A pre-made script and template set is provided if you just want something to drop in and use. Alternatively, if you are capable of writing your own JavaScript, you can instead code against the popups directly to do things like AJAX new content and display it in a popup as certain elements are interacted with.

To use the custom popups, you will need to import the Custom Popup script:

```
importArticles({
 type: 'script',
 articles: [
 // ...
 'w:c:dev:ReferencePopups/custom.js',
 // ...
 ]
});

```

And you will need to copy these 2 templates onto your wiki to make use of the script:

* Template:Popup
* Template:PopupContent

The templates describe how to use them.

An important thing to note is that the custom popup script *will* use the user's ReferencePopup configuration even though the gear icon doesn't appear in custom ones. This means that if the popup is in click mode then attaching popups to page elements that already have their own scripts can have strange consequences. Unlike normal popups, custom ones are *never* sticky and can't be disabled though.

You can also construct custom skins for you custom popups as well. An example of this is on the demo page, you can see the CSS for it over here.