Help:Gadget-HotCat

From Wikimedia Commons, the free media repository

HotCat is a Javascript extension of the MediaWiki user interface. It augments the category bar with quick links to remove, change, or add categories. It can be activated in the "Gadgets" tab of Special:Preferences.

[edit] Browser compatibility

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

Firefox 3	OK
Firefox 2	OK	FF 2.0.0.19 on Win XP Pro, SP2
Internet Explorer 8	OK
Internet Explorer 7	unknown	presumed OK
Internet Explorer 6	OK	Win XP Pro, SP2
Konqueror	OK
Opera	OK	Opera 9.50 on Win XP, SP2
Safari 3/Mac	unknown	presumed OK
Safari 3/Win	OK	Safari 3.0.4 & 3.1.1 on Win XP Pro, SP2
Safari 2/Mac	unknown
Safari 2/Win	don't care	Early Safari versions for Windows are known to be buggy. We don't cater to broken browsers (well, except IE :-) Users should upgrade their browsers to Safari 3.
Firefox 1.5	OK	Firefox 1.5.0.9 on Red Hat 4 Enterprise
IE/Mac	unknown	needed?
IE 5.5	unknown	needed?

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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

You can even give a sort key together with the category. Just write after the category name a vertical bar ("|"), followed by the sort key under which the page shall be sorted within that category's list.

[edit] 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 Category:Buzet.

[edit] 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 keyboards; 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.

[edit] User configuration

Some aspects of HotCat can be configured by the user:

• The user may set the timeout between a keypress and the refresh of the suggestion list. The default is 100 milliseconds. To change this to some other value, add the following to your monobook.js or other skin-specific user JS (for instance, if you're using the "modern" skin, add it to modern.js):

JSconfig.keys['HotCatDelay'] = 200; // Or whatever other value you prefer

• The user may change the width of the edit box. The default (and minimum size) is 40 characters. If you find that too small, add the following to your skin-specific user JS:

JSconfig.keys['HotCatEditBoxWidth'] = 80; // Or whatever other value you prefer

[edit] Installing HotCat on another Wiki

If you want to install HotCat on another Wiki, follow the procedure outline here:

1. Enable the API on your wiki. You don't need to enable the write API. $wgGroupPermissions["*"]["read"] may be set to false if you have a private Wiki (one that allows reading only if logged in).
2. Make sure you have the Gadgets extension installed and enabled.
3. Make sure your wiki includes ajax.js on all pages. If you're using some Javascript framework on your Wiki, either textually copy the function sajax_init_object into the HotCat file you'll copy in step 5, or rewrite HotCat to use your framework. If you're not using some framework, either set up your wiki to serve ajax.js, or again textually include function sajax_init_object in the HotCat source.
4. Make sure your wiki includes wikibits.js on all pages. HotCat needs the function addOnloadHook from that file to launch. If your Wiki has some other way to lauch Javascripts, modify the HotCat source accordingly.
5. Get HotCat from MediaWiki:Gadget-HotCat.js.
6. Install that file, possibly modified as outlined in steps 3 and 4, on your Wiki as MediaWiki:Gadget-HotCat.js.
7. Write a definition for it in MediaWiki:Gadget-HotCat (on your Wiki), and add it to MediaWiki:Gadgets-definition (also on your Wiki).
8. Go to Special:Preferences on your Wiki and check the gadgets section. HotCat should appear there. Select it and save your preferences.
9. Done.

If you want to include HotCat on a public WMF Wiki (Wikipedia, Wikinews, or oher WMF project), you may skip steps 1 to 4.

Note that our HotCat implementation has some specialties concerning category redirect and disambiguation detection which may or may not be appropriate for your Wiki. The HotCat version at the English Wikipedia has been modified with respect to where it inserts categories, and it uses OpenSearch for its suggestions. If the Commons version of HotCat doesn't meet your needs, give the English Wikipedia version a try. The procedure remains the same.

Also note that the Commons version of HotCat is guaranteed to work only with the skins installed at the Commons. It should work out-of-the-box for all modern skins, though. The version from the English Wikipedia does not work on the old skins ("Cologne Blue", "Standard"/"Classic", and "Nostalgia"). The Commons version does. Also, the English Wikipedia version does not work on the upload form, whereas the Commons version does.

Also note that HotCat is an old script. It does not use any advanced framework like jQuery, and it does pollute the global namespace quite a bit. It works, but its code is rather messy.

[edit] Problems?

If you have any problems with HotCat, report them at MediaWiki talk:Gadget-HotCat.js. Please note that we cannot give, in general, support for installing or running HotCat on other Wikis.