How to Use Custom Fonts in JavaScript Reports

Fonts 101

All components of ActiveReportsJ operate against a web browser environment.

• The standalone report designer application is built with Electron that uses Chromium to display the user interface
• The report designer and report viewer components are parts of a web application that runs in the browser on a user's machine
• PDF, Tabular Data, and HTML Export Filters use a web browser environment to measure report content

A typical report consists of textual content that the browser renders using shapes called glyphs. Font resources contain information that maps character codes to glyphs representing these characters. Browser, therefore, needs to have access to font resources to display the text as expected.

All textual items in ActiveReportsJS have several font properties, including

• Font Family: the font ID, f.e. Arial, Calibri, or Times New Roman
• Font Style: normal or italic
• Font Weight: Thin, Extra Light, Light, Normal, Medium, SemiBold, Bold, Extra Bold, Heavy

A unique combination of these three properties is called Font Face. A font family typically consists of several font faces, usually represented by separate files. For instance, here is the screenshot of the Calibri font folder in Windows

When ActiveReportsJS renders a report, it translates these font properties to font-family, font-style, and font-weight CSS style properties. It relies on a browser to resolve associated font resources and extract required glyphs. The browser has two ways to access font resources; locally on the system a browser is running or by download.

Using downloadable font resources is easy to maintain; all modern browsers support it, and it guarantees the consistent output of textual content across all the environments. Besides, the ActiveReportsJS PDF Export requires downloadable fonts because it embeds their subsets in a PDF document.

Therefore, the best way to ensure the consistent report output across all the environments is to configure ActiveReportsJS components to access downloadable font resources. This article offers a step-by-step guideline to achieve that.

To begin, decide which font families you will use in reports. It could be standard fonts, such as Arial, Times New Roman, or Helvetica. It could be one or more web fonts. We use Montserrat font for our demo reports. In any case, make sure that you have all font face files for all font families. ActiveReportsJS supports the following font formats:

Configuring the Standalone Designer Application

You can find the standalone report designer font configuration at the following locations.

• Windows : %AppData%\ActiveReportsJS Designer\fontsConfig.json
• macOS: ~/Library/Application Support/ActiveReportsJS Designer/fontsConfig.json
• Linux: ~/.config/ActivereportsJS Designer/fontsConfig.json

Create a folder named Fonts and copy to it all the files for all the fonts faces that you will be using for reports

Then, open the fontsConfig.json file in your favorite JSON editor. This file contains descriptors for font faces that a report author will use for textual content. In the path property, specify the absolute path to the parent folder of the Fonts directory. Replace the default items of the descriptors array with the descriptors of the desired font faces. Each descriptor includes the following properties:

For example, to allow the Regular, Italic, and Bold faces of the Montserrat font, you can use the following descriptors:

{
    "name": "Montserrat",
    "weight": "400",
    "style": "normal",
    "source": "Fonts/Montserrat/Montserrat-Regular.ttf"
},
{
    "name": "Montserrat",
    "weight": "400",
    "style": "italic",
    "source": "Fonts/Montserrat/Montserrat-Italic.ttf"
},
{
    "name": "Montserrat",
    "weight": "700",
    "style": "normal",
    "source": "Fonts/Montserrat/Montserrat-Bold.ttf"
}

Run the standalone designer application, add a TextBox in a report's body and make sure that you can set its Font Family property to one of the fonts you enumerated in the fontsConfig.json file, and all the font faces are correctly displayed.

Configure ActiveReportsJS-based Applications

An application that displays reports in the report viewer, exports reports to PDF, or hosts the report designer component should use the same configuration you created for the standalone designer application. The easiest way to achieve that is to copy those above Fonts folder and fontsConfig.json file to an application's static assets folder. This folder varies for different front-end frameworks. Here are some examples:

• Using the Public Folder for React applications created with create-react-app
• Assets configuration for Angular applications. If the Fonts folder and the fontsConfig.json file is copied to the assets folder, then modify the source properties of font descriptors in the fontsConfig.json file so that they would start with assets, for example

{
    "name": "Montserrat",
    "weight": "900",
    "style": "italic",
    "source": "assets/Fonts/Montserrat/Montserrat-BlackItalic.ttf"
}

• Static Assets Handling for Vue applications

Finally, the application should call the registerFonts method of the FontStore object with the URL of the fontsConfig file. This code should run before the application starts displaying or exporting reports. Note that the registerFonts method is asynchronous and returns the Promise object.

The code that calls this method can also wait until this returned Promise resolves before loading reports in the viewer component or exporting them.

For pure JavaScript applications:

<script src="https://cdn.grapecity.com/activereportsjs/2.2.0/dist/ar-js-core.js"></script>
<script>
  GC.ActiveReports.Core.FontStore.registerFonts(
    "/resources/fontsConfig.json" // replace the URL with the actual one
  )
</script>

For Angular, React, and Vue applications:

import { Core } from "@grapecity/activereports";
Core.FontStore.registerFonts("/assets/fontConfig.json") // replace the URL with the actual one

You can find examples of such a code in our live demos.

Configure the Report Designer Component

To ensure that the report designer component displays the registered fonts only, set the fontSet property of the designer instance to registered. In addition, if you want to ensure that newly added report items have one of the registered fonts by default, you could use the Custom Init Template feature.