MediaWiki:Gadget-HotCat.js/Documentation

HotCat is a Javascript extension of the MediaWiki user interface. It augments the category bar with quick links to remove, change, or add categories.

Browser compatibility
HotCat has been tested and is known to work on the following browsers:

Additionally, the script has been tested on all skins using Firefox 2.

Like for many other scripts at WikiMedia projects, a DOM Level 2 compatible browser is a prerequisite. Ajax is used for the category suggestions.

If Javascript is disabled, the script will of course not do anything. If Javascript is enabled, but Ajax is disabled, HotCat can still be used to add, change or remove categories, but it won't be able to propose suggestions for categories.

User interface
Whenever a page is loaded, HotCat looks for the category bar. If there are visible categories, it adds links to easily remove, change or add categories. Due to space constraints (and also to avoid internationalization issues), these links use symbols instead of text: The new links are:
 * "(-)" after a category: when clicked, the category is automatically removed.
 * "(±)" after a category: when clicked, an input field to change this category is opened.
 * "(+)" at the end of the list of categories: when clicked, an input field to add a category is opened.

Note that HotCat only supports modifying the visible categories. Hidden categories are hidden anyway unless made visible through a setting in your preferences. And even when and if they are shown, they are typically maintenance categories that are transcluded onto the page through some templates, and HotCat cannot change these anyway.

Removing a category
To remove a category, simply click the "(-)"-Link next to the category name. If the page does indeed contain this category, HotCat will remove it automatically. It will
 * 1) open a new window or tab in your browser with the current page opened for editing,
 * 2) hide the whole edit form, so that you cannot edit,
 * 3) edit the page to remove the category, and
 * 4) save the page.

If the category does not exist in the page text itself but was transcluded onto the page from a template or other transclusion, HotCat will still open the page for editing, but it won't hide the page content and it won't edit or save the page. Instead it will present an error message stating that it could not find the category.

Unfortunately, it is currently not possible for HotCat to detect such transcluded categories and omit the "(-)"-Link (and also the "(±)"-Link) on such categories. This would need a server-side change such that the server would mark such transcluded categories, for instance by giving them a special "class". Without such server support, HotCat would need to make an additional call to the server to determine which categories were transcluded. This was deemed potentially too expensive.

Changing a category
To change a category, click the "(±)"-Link next to the category name. This will open the input box where you can enter a new category name.

Adding a category
To add a category, click the "(+)"-Link at the end of the category line. This will open the input box where you can enter a new category name.

Input box
The input box of HotCat is very simple: a text field to enter the new category name, an indicator icon, and an "OK" and a "Cancel" button.

The indicator icon tells you whether or not the category name you've entered exists. A icon means that there is no such category yet. You can still add the catgeory, but it will show up as a red link, and you should, after having added the category, click that red link and enter a brief description and parent categories to this new category. A icon shows that there already is a category with the name you've entered.

When you start typing, HotCat will display a list of suggestions above or below the text input field. Clicking one of these suggestions will copy it into the text field. Double-clicking a suggestion is the same as clicking once and then clicking the "OK" button: HotCat will add the double-clicked suggestion automatically.

In the example shown here, we've entered "Alps of", and HotCat presents us with a list of possible completions. The first suggestion has already been copied into the text box, but the added text is selected, so that it will be overwritten when we keep on typing. Entering " S" reduces the suggestion list accordingly.

Clicking on "Alps of Switzerland" will then copy that into the text field and close the suggestion list (since there are no more suggestions, i.e., categories beginning with "Alps of Switzerland" as a prefix).

Clicking the "Cancel"-button would now abort the operation, clicking "OK" would tell HotCat to go on and add the chosen category.

Category redirects and disambiguations
HotCat tries to automatically resolve redirects between categories when the "OK"-button is clicked (or when a suggestion is double-clicked). If the selected category X is a redirect to another category Y, HotCat will automatically add the category Y instead of X.

Similar processing is done for disambiguation categories. If HotCat detects that the chosen category is actually a disambiguation category, it will present again a suggestion list, this time filled from the categories being disambiguated. If, for instance, you entered "Buzet" as the category and then clicked "OK", you would see the suggestion list shown here, as these are all the categories mentioned at.

Control-clicking
Normally, you would want HotCat to automatically process your category changes. However, sometimes you might want to check what HotCat does before saving the modified page. To do so, use "control-clicking". Hold down the Control-Key (marked "Ctrl" on many keyboard; on German keyboards, it's often called "Strg") while clicking with the mouse on the "(-)"-Link, or on the "OK"-button, or while double-clicking a suggestion from the list. In that case, HotCat will still open the page for editing and will modify it, but it will neither hide the edit screen nor save it automatically. Examine the changes at your leisure, and then click "Save page" to commit the changes.

Problems?
If you have any problems with HotCat, report them at MediaWiki talk:Gadget-HotCat.js.