Icon path to icon class migration

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

Jenkins core has removed GIF and PNG icons as of Jenkins v2.333, in favor of the previously added SVG icons.

Plugins, that don’t interact with icons at all, are unaffected by this change.

Examples of area which require changes

  • If a plugin reads icons from its icon path, it typically does the following in jelly:

<img src="${imagesURL}/16x16/fingerprint.png" alt="" height="16" width="16" />
<!-- or -->
<l:task icon="images/24x24/document.png" href="" title="${%Modules}" />
  • or in groovy:

img(width:"16", height:"16", src:"${imagesURL}/16x16/next.gif")
  • A plugin can do that in Java too, but that is, by far, less common.

Maintaining support for legacy icons and modern icons

Jelly offers a couple of properties to access an icon class instead of an icon path. Jenkins core will display a GIF, a PNG or an SVG, based on the Jenkins version used. The properties <l:icon class> and <l:task icon> are used based on the location the icon is displayed in.

The format is icon-<icon> icon-<size>. <icon> represents the name of the icon that used to be read from a path. <size> represents the icon size. The following values for <size> are available:

Path size attribute <size> attribute

16x16

sm

24x24

md

32x32

lg

48x48

xlg

Pick the appropriate <size> attribute according to the path size the icon has.

Jelly example:

<l:icon class="icon-fingerprint icon-sm" />
<!-- or -->
<l:task icon="icon-document icon-md" href="" title="${%Modules}" />

Groovy example:

l.task(icon:"icon-next icon-sm")

More information about Jelly tags provided by core to display icons can be found in its jelly documentation.

I still need more help?

Contact the UX sig on Gitter.