Using icon fonts with Ogma

Why use font icons?

Oftentimes icons are a good way to visualize the category of a node. There are different ways of adding an icon, it can be a raster image (.png or .jpg), but with scaling, the icon would become blurry. Vector fonts are solving this problem by delivering a set of vector icons in a form of a custom font file. This is widely used on websites, and rendering of icons are performed there by the browser engine. In Ogma, text rendering in all the modes but SVG is handled by Ogma itself, so in order to use icon fonts, you would need to preload and define the icons for sampling that is required for the further rendering.

How to load an icon font

Here and below, we will use one of the most popular free web icon fonts, FontAwesome. It is distributed as an archive that you can host yourself on your website, or you can use the CDN version, but you have to make sure that the correct CSS file is included and the referenced font files (.ttf or .woff) are available.

Let's use the latest version of FontAwesome in our example:

<link
  href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/all.min.css"
  rel="stylesheet"
/>

The fonts are loaded asynchronously, so we advise to force the font loading by including an invisible icon on your page or use document.fonts API, implemented by the modern browsers:

document.fonts.ready.then(() => {
  // add icon rules here:
  ogma.styles.addNodeRule({
    ...
  });
});

You may also use WebFont Loader project that ensures the presence of document.fonts API.

Another trick that you can see in our example is to force loading of the external icon font into the browser by adding a hidden (opacity: 0) or off-screen element, that is using the icon font.

Some of the icon fonts are also available through package managers, so the font files can be embedded into your javascript bundle. That doesn't change the way icons are used with Ogma, so we would not focus on that in this tutorial. You can find tutorials on that depending on whether you are using Webpack or other package loaders, but the core concept remains the same: you need to have the font files and mapping of the icons to their unicode sequences.

You can omit the CSS file if you are not going to use the icon font in your UI, but you would still have to trigger loading of the webfont into your application.

@font-face {
  font-family: 'Font Awesome 5 Free';
  /* references to the font files to load */
  src: url(...);
}

How to configure node icon rule

When using icon fonts with Ogma, you would need to provide the unicode value for the icon and the correct font name. Some fonts may have the glyphs defined for a certain font style, in case of FontAwesome 5, it's bold.

ogma.styles.addNodeRule({
  icon: {
    content: `\uf030`, // unicode symbol for `fa-camera` icon,
    font: 'Font Awesome 5 Free', // you can look up the font-face in the CSS-file
    style: 'bold' // some of the FontAwesome icons are available only in weight:900
  }
});

// or, alternatively, you can use classes
ogma.styles.createClass({
  name: 'nodeWithIcon',
  nodeAttributes: {
    icon: {
      ...
    }
  }
});
ogma.getNode(id).addClass('nodeWithIcon');

How to use an icon in badge

Icons can be used in node badges just the same way as for the node background:

ogma.styles.addNodeRule({
  badges: {
    topRight: node => {
      if (node.getData('type') === 'picture') {
        return {
          text: {
            content: '\uf030',
            font: 'Font Awesome 5 Free',
            style: 'bold',
            color: 'blue'
          }
        };
      }
      return null;
    }
  }
});

Vector icon fonts can be used in the same way in the edges texts:

How to retrieve the icon Unicode value

If you want to use the CSS classes provided by the font rather than the unicode values to get the icons, you can use the following trick:

// dummy icon element to retrieve the HEX code, it should be hidden
const placeholder = document.createElement('span');
document.body.appendChild(placeholder);
placeholder.style.visibility = 'hidden';

// helper routine to get the icon HEX code
const getIconCode = className => {
  placeholder.className = className;
  const code = getComputedStyle(placeholder, ':before').content;
  return code;
};

// cache it once, because you would want to avoid calls to the DOM
const iconCode = getIconCode(`fa fa-camera`);
const fontName = 'Font Awesome 6 Free';

// Use it in your style rules
ogma.styles.addNodeRule({
  icon: {
    content: iconCode,
    font: fontName,
    style: 'bold',
    content: iconCode
  }
});

Export

Visual export functions of Ogma will work with icon fonts without problems: you only have to make sure that minVisibleSize parameter is adjusted in such a way that your icons would appear while exporting to the selected image size. However, if you use SVG export, there is a caveat: the icons are embedded into the SVG document as text, using the custom font that was available in your application. The exported SVG file will rely on that font to display the icons, and if it's not install on your system, the icons will not be displayed correctly. You can choose the embedFonts: true option in your export call, so that your exported files will have the correct icons in system preview and when you open your exported .svg file in the browser.