Template:Top icon/doc

This is a metatemplate used to help build top icons, the little (usually 15x15 pixels) icons in the top-right area of user pages or articles.

Usage


Extra options: 
 * style       = Adds this to the style of the body.
 * width       = Uses a different width for the images. For icon_nr to function, all uses of topicon on a page, require the same width.
 * user        = Adds a category to be added in userspace.
 * main        = Adds a category to be added in article mainspace.
 * subpage     = For categorization on subpages (default = no).
 * nocat       = Disables the automatically added category (default = no).

Any top icons that use this template are safe for sitenotices, etc. However, when sitenotices are active, the icons are likely differently aligned and may cross the header line. At the moment there is no way to fix this, and user top icons have a lower priority than the top icons for articles (which do work in all cases). If you use this template, however, your icons will be automatically fixed permanently once we do find a solution.

Example
Creates these three icons, from left ? right: account creator, rollback, autoreviewer.

Purpose
The top icons are a hack. They originate from the protection symbols. The only supported top icons are the four used in article space; the protection lock, the spoken article speaker icon , the good article symbol and the featured article star.

More and more often, editors have been using the same trick to add custom icons to their user pages. However, due to how the icons are implemented, they have a tendency to break rather easily, for instance when sitenotices are active. Because it is impossible to correct this for each and every user page every time the top icons are broken (not to mention a waste of valuable editor time), a new template (top icon) and class (topicon) were introduced to make it simpler to support the icons.

Note that officially, the top icons on user pages are allowed to break at any time. Other technical changes that are important to the entire MediaWiki software or changes to the main/article namespace will always be more important than keeping the user space's top icons working. This template is therefore meant to simplify support, not to guarantee it.

Technical details
CSS is used to move a small piece of HTML from the content area of a wikipage to somewhere else on that page, usually in the top-right at the same height as the title of the wikipage. Because CSS is used, the icons require specific CSS for each individual skin. Currently only Monobook, Modern and Vector are supported.


 * Each top icon should use the class "topicon". This is required to correct the position of the icon for each skin.
 * The top icons are hidden with " " by default. The skin-specific CSS unhides them, so that the icons are only visible in skins that support the icons.
 * The skin-specific CSS determines the vertical position of top icons. Thus the style option " " should not be used by user top icons.
 * Top icons use the CSS property " " to determine how far from the right of the page the icon should be; article namespace icons, however, have fixed positions.
 * The property " " is used by skin-specific CSS to correct the default right offset if needed. This is also used by the lede edit section gadget to correct offset even further.
 * If individual top icons require vertical offset relative to other top icons, they can use  or   properties.