Template:Infoicon/doc

Purpose

This template provides a method to rapidly include an icon and link inline with text, such as inside of a paragraph or in a bulleted list.

Automations

• Automatically detects and corrects a handful of mismatches between image filenames and desired article names.
• Unless param new is provided, utilizes images from a sprite sheet to reduce server load and speed up page loading time for visitors.

Usage

The template accepts the following parameters:

{{{1}}} = image name

symbolonly = yes (optional)(rare)

link = something (optional). Changes the link's target to the specified value. If set to no, prevents linking.

text = something (optional). Changes the link's text to the specified value.

plural = s (optional). Generally "s" or "es" as a plural suffix.

For irregular plural suffixes like "knife" → "knives", instead use text.

ui = yes (optional). Prevents the white glow which improves accessibility from being applied (useful for white UI elements)

new = yes (optional)(rare). Should be used the desired icon has not been incorporated onto the automated sprite sheets (e.g., it's brand spanking new to the game)

Examples

• {{infoicon}} → Infoicon: parameter {{{1}}} was not provided
• {{infoicon|PCB}} → PCB
• {{infoicon|PCB|icononly=yes}} →
• {{infoicon|PCB|plural=s}} → PCBs
• {{infoicon|PCB|link=no}} → PCB
• {{infoicon|PCB|link=PCBWay}} → PCB
• {{infoicon|Electronics II|text=Circuit City}} → Circuit City
• {{infoicon|Worker|ui=yes}} → Worker
• {{infoicon|Worker|plural=s|ui=yes}} → Workers
• {{infoicon|Workers|ui=yes}} → Workers
• {{infoicon|Unity|ui=yes}} → Unity
• {{infoicon|Unity Large|ui=yes}} → Unity Large
  • This is an example of an image which is too large and busy to display properly as an infoicon (see File:Unity Large.png).

Creating and modifying sprite sheets

What are sprite sheets?

Sprite sheets are composite images consisting of multiple small files such as icons. The use of CSS and sprite sheets allows for many of these images to be displayed while only requesting a single file from the wiki's server. This allows for improved browser-side caching across the entire wiki and prevent images from "popping in" as they load individually, bettering the user experience. Additionally, they drastically reduce uncached (e.g., first visit) load times of pages that make use of a large number of these assets, such as the main page: Official Captain of Industry Wiki.

Who can create them?

• Any user can prepare the sprite sheet image and CSS file.
• For security reasons, steps marked below with ** require assistance from a user in the Interface Administrator user group (see list of Interface Admins).

When should a new sprite sheet be created?

When a large number of icons have been added to the game or updated. The performance benefits of sprite sheets are generally not realized with only a small amount of icons on a sheet. Thus, the recommended minimum number of new icons or updated icons is no fewer than five. Individual icon files can still be called with the new parameter (see Usage section above).

When should an existing sprite sheet be updated?

Almost never. Mediawiki's file engine sorts and stores files into dynamically-balanced subdirectories. When a new version of a file is uploaded, it will almost always be placed into a new file directory. This action is seamless when images are called through the traditional [[File:Filename.png|size|thumb|right]] syntax, however it breaks all existing references to previous file version which this template relies on. In a nutshell, advanced editors with an understanding of the application of these concepts can indeed update sprite sheets, however doing so without interrupting the live user experience requires careful timing and a perfect edit, thus it is not recommended.

If we shouldn't update existing sprite sheets, then how do we add more?

• Each CSS class references the sprite sheet image used so there is effectively no upper limit to the number of new sprite sheets that can be added. In other words: just add another sprite sheet.

If we shouldn't update existing sprite sheets, then how do we update icons that the developers changed?

• CSS obeys precedence. Subsequent declarations of the same class name overwrite precious declarations. So long as your CSS is added to the sitewide stylesheets below the old version, it will be what applies.
  • Webdev nerd note: Explanations of the !important property and specificity rule have been purposely omitted above for the sake of simplicity and applicability to the average wiki editor.

How are they created?

1. Resize the source image files to the desired size for use, such as 16x16 pixels.
   • The recommended method is to use the free GIMP editor, though most any modern raster image editing software is likely suitable.
     • Batch processing tools such as the free GIMP plugin BIMP can greatly expedite this process.
     • If your image editor provides the option, bicubic sampling generally provides the best result.
     • Be careful not to accidentally remove background transparency when saving.
2. Use a sprite generation tool to merge the images into a single file and generate the CSS stylesheet.
   • The recommended tool is the web-based Toptal CSS Sprites Generator.
     • Options selected should be "Padding between elements (px): 1" and "Align elements: Top-down".
     • Download the composite image and copy the CSS stylesheet output to your text editor of choice.

Naming convention

• CSS class names must begin with sprite-16- or sprite-24- (depending on image size)
• CSS class names must end with the name of the item or UI element it refers to. Use proper case, omit spaces, and replace any & (ampersands) with And.
• Examples:
  • {{infoicon|Coal}} → Coal → .sprite-16-Coal { ... }
  • {{infoicon|Copper Ore Crushed}} → Copper Ore Crushed → .sprite-16-CopperOreCrushed { ... }
  • {{infoicon|Metallurgy & Smelting}} → Metallurgy & Smelting → .sprite-16-MetallurgyAndSmelting { ... }

How are they added to the wiki?

1. Upload the sprite sheet to the wiki using Special:Upload like any other image.
   • The standard naming convention is Sprites-<category>-<#>.png, where category is a description of this group of icons and # is the icon height in pixels. E.g., Sprites-Items-16.png.
   • Please categorize the file page with [[Category:Sprite sheets]] so other editors can find it later.
2. Hover the "Original File" link on the file's page and note the URL displayed in the browser after https://wiki.captain-of-industry/. In the case of Sprites-Items-16.png, this is images/1/1f/Sprites-Items-16.png
   • Replace all instance of css_sprites.png in the previously-generated CSS text file with this filename.
3. ** Double-check your work and append the prepared CSS to Mediawiki:Common.css.