IconService

The IconService functions as a central definition and delivery method for all sorts of icons: image icons as well as font icons.

Different kinds of icons

Image icons are those that display a small icon using an image file. Each individual icon of that kind refers to exactly one file on the disk. Font icons are bundled into a single web font file that holds all icons available via a this specific font. Web fonts are normally used to change typographical aspects of the web with well known fonts such as Arial, Times New Roman and the like. Each glyph in a web font represents one character of text. Icon fonts are a specific kind of web fonts where glyphs don't represent a character but an icon.

Image icons are very colorful most of the time, whereas font icons are always monochrome. The color of an image icons cannot be changed; the color of a font icon can be adjusted by changing their text color. Icon fonts may be manipulated in many ways, most notably they can be scaled to any size possible without losing their rendering quality. This is the main advantage over image icons that can only be delivered in a single scale and a predefined coloring.

The IconService is able to make both kinds of icons available to the system likewise as far as possible with regards to their different nature (see above). All icons are addressible by their unique identifier. All icons fall into at least one category that describe their origin and nature.

Definition image icons

Image icons are defined by being available on an "icon search path". This is a list of locations (on disk), where image files are looked up for a specific identifier. The icon search path is configured by the {JQueryPlugin}{IconSearchPath} and defaults to FamFamFamSilkIcons, FamFamFamSilkCompanion1Icons, FamFamFamFlagIcons, FamFamFamMiniIcons, FamFamFamMintIcons. The named icon will be picked found first on this path of topics where icons are attached to.

Definition of font icons

Font icons are defined by the {JQueryPlugin}{IconFonts} setting. This is a list of icon font definitions, i.e. how they are named, and which css file must be loaded into a web page to make them available. The default setting is:

$Foswiki::cfg{JQueryPlugin}{IconFonts} = {
  'fontawesome' => {
    'prefix' => 'fa',
    'definition' => '$Foswiki::cfg{PubDir}/$Foswiki::cfg{SystemWebName}/JQueryPlugin/plugins/fontawesome/fontawesome.json',
    'plugin' => 'fontawesome',
  },
  'material' => {
    'prefix' => 'ma',
    'definition' => '$Foswiki::cfg{PubDir}/$Foswiki::cfg{SystemWebName}/WebFontsContrib/material-icons/material.json',
    'css' => '$Foswiki::cfg{PubUrlPath}/$Foswiki::cfg{SystemWebName}/WebFontsContrib/material-icons/font-face.css', 
  },
};

Note that Foswiki does only ship Fontawesome icons by default. Material icons are part of the WebFontsContrib extension that you might want to install in addition. Its definition section in the {JQueryPlugin}{IconFonts} setting is ignored in case of the definition file not being present.

Each entry is of the following format:

   '<fontName>' => {
      'prefix' => '<string>',
      'definition' => '<definitionFile>',   
      'plugin' => '<jQueryModule>',
      'css' => '<cssUrl>'
   }

• fontName: unique identifier
• definitionFile: file path to a file holding a font definition (more about it below)
• plugin or css: either an icon font is loaded by means of a jquery module being loaded; this module then holds any further means to load the required assets into a web page; or the css url that is to be added to the page.

A definitionFile itself defines the individual icons themselves, i.e. it mapps icon identifier to the actual glyph in the icon font. The definitionFille lists all identifiers that might be used in a VarJQICON macro:

%JQICON{"<prefix>-<identifier>"}%

The <prefix> part specifies which of the available icon fonts the <identifier> relates to. For instance fa-pagelines load the fontawesome jQuery module and then generate the according markup to display the icon.

Definition file for an icon font

A definitionFile refered to in an fontName entry of the {JQueryPlugin}{IconFonts} setting lists all available icon identifiers. It may also list aliases and categories that icons belong to grouping them into meaningful partitions. JQueryFontAwesome comes with a certan set of categories such as:

• Accessibility Icons
• Brand Icons
• Chart Icons
• Currency Icons
• Directional Icons
• File Type Icons
• Form Control Icons
• Gender Icons
• Hand Icons
• Medical Icons
• Payment Icons
• Spinner Icons
• Text Editor Icons
• Transportation Icons
• Video Player Icons
• Web Application Icons

A definition file has got the format:

{
   "icons": [
      {
         "id": "<string>",
         "name": "<string>",
         "unicode": "<codepoint>",
         "categories": [
            "<string>",
            "<string>",
            ...
         ],
      },
   ]
}

• id (mandatory) defines the icon id unique among all icons of this font
• name: icon name in human readable form, defaults to id if not present
• unicode: codepoint as defined in the web font
• categories list of categories that the icon belongs to

Each icon in an icon font automatically is in the fonticon category as well as in the fontName category (e.g. fonticon, fontawesome, Payment Icons).

Each icon of an image icon automatically is added to the category naming the topic it is attached to, e.g. FamFamFamSilkIcons.