Icons

This document is referring to a past Scout release. Please click here for the recent version.

A lot of Scout widgets support icons. For instance a menu item can show an icon next to the menu text. Icons in Scout can be either a bitmap image (GIF, PNG, JPEG, etc.), an SVG or a character from an icon-font. An example for an icon-font is the scoutIcons.woff which comes shipped with Scout.

It’s a good practice to define the available icons in your application in a class that defines each icon as a constant. Create a class Icons in the shared module of your project. These constants should be references, when you set the IconId property in your code.

For bitmap images you simply specify the filename of the image file without the file extension. Place all your icon files in the resource folder of your client module. Assuming your project name is "org.scout.hello", the correct location to store icon files would be:

org.scout.hello.client/              # Client project directory
  src/main/resources/                # Resources directory
    org/scout/hello/client/icons/    # Path to icons
      application_logo.png
      person.png
      ...

Listing 1. Icons.java

// Bitmap image (references icons/application_logo.png)
public static final String ApplicationLogo = "application_logo";

// Character from icon-font scoutIcons.woff (default)
public static final String Calendar ="font:\uE003";

// Character from a custom icon-font
public static final String Phone ="font:awesomeIcons \uF095";

Listing 2. Usage of iconId in a Scout widget

@Override
protected String getConfiguredIconId(){
  return Icons.Calendar;
}

Font Icons

The icons used by Scout itself are mainly font icons. Even though font icons are scalable, an icon can get very thick when the size is increased, which is not always desired. To overcome that, Scout icons come in 2 flavors: regular and light.

The regular icons can be used, if the icon is displayed at about 16px. This is the case for most widgets (menu, button etc.) If the icon should be displayed larger, the light icons can be used.

To use a light icon for your custom widget, just set the font-weight to @icon-font-weight-light.

If you create a custom icon font (or use an existing one), you may want to use icons that are compatible with the Scout icons in terms of line width. This allows you to use the Scout icons and your custom icons side by side. Alternatively, only use your custom icons and forget about the Scout icons.

The scout icons use the following dimensions:

Regular: 1.5px line width and 24px artboard height
Light: 1px line width and 24px artboard height

Using a custom icon font

You can use your own icon font. The required file format for an icon font is .woff. For the following examples we assume the name of your font file is awesomeIcons.woff. The following steps are required:

Place the font file in the WebContent/fonts directory of your html.ui module. This makes it available for http requests on the URL http://[base]/fonts/awesomeIcons.woff.

Create a CSS/LESS definition to reference the icon font in stylesheets (e.g. in a file called fonts.less). Make sure the definition is added to the index.less of your project.

Listing 3. The CSS/LESS font definition should look like this:

@font-face {
  font-family: awesomeIcons;
  font-weight: normal;
  src: url('fonts/awesomeIcons.woff') format('woff');
}

/* Overrides definitions in fonts.css > .font-icon
* Use iconId 'font:awesomeIcons [character]' in Scout model.
* See icons.js and usage of this class to see how iconId is used.
*/
.font-awesomeIcons {
  font-family: awesomeIcons, @font-default-family;
}

To check if your CSS definition is correct, you should download the CSS file directly via URL and check if the CSS file contains the required font definition. Have a look at your index.html to find the path to your CSS (e.g. http://[base]/yourapp-theme.css).

When you request resources from the WebContent folder via http, Scout will find resources from other modules on the classpath too. Thus the scoutIcons.woff is always available in a Scout project. However, you must avoid naming conflicts, since at runtime all files exist on the same classpath.

How to create a custom icon font

Here’s what we do to create and maintain our own icon font scoutIcons.woff. There may be other methods to achieve the same.

To create and modify our icon font we use the online application IcoMoon. IcoMoon allows you to assemble a set of icons from various sources (e.g. FontAwesome or custom SVG graphics) and create a font file from that set.

You can export/import your icon set from and to IcoMoon, and you should store the files exported from IcoMoon in a SCM system like GIT. IcoMoon stores all important data in the file selection.json. Make sure you also store the raw SVG graphics you’ve uploaded to IcoMoon in your SCM, in case you have to change a single icon later.

To edit the icon font in IcoMoon follow these steps:

Import selection.json in IcoMoon, click on the "Import Icons" button.
With the Select tool (arrow) you select the icons you want to add to your set. You can also add one or more characters from other icon fonts like FontAwesome by choosing Add Icons From Library…
Your can import your custom SVG graphics with Import to Set, which you find in the hamburger menu on the icon set. The SVG graphic should have the same size as the other icons in the set and must use only a single color, black. The background must be transparent. Hint: the filename of the SVG graphic should contain the unicode of the character in the font in order to simplify maintencance. Only use unicodes from the Private Use Area from U+E000 to U+F8FF.
When you’re happy with your icon set, you hit the Generate Font button in the footer in IcoMoon. On the following page you can set the unicode of each icon/character. Click on the prefences button (cog icon), to set the name of your icon font (e.g. scoutIcons). Finally click on Download and you receive a ZIP file which contains the new selection.json, and font files like .ttf and .woff.
When you’ve added new unicodes to the icon font, you should also update Icons.java and add constants for the new characters. When you’re using Scout JS you should also update icons.js and icons.less.
Important! don’t forget to check in the new selection.js to your SCM.

Tools

Windows tool Character Map: first you must install your custom TrueType Font .ttf in Windows. Simply double-click on the .ttf file and choose Install. After that you can start Character Map and browse through the font.
The ZIP archive from IcoMoon contains a file demo.html. This file shows a preview of your icon font. Works in Chrome, but we had trouble viewing the font with Firefox.
This tool from Wikipedia also creates a preview for an icon font: Vorlage:Private-Use-Area-Test. Icon font must be installed first.