Jasper Reports: Adding Custom Fonts

I was recently tasked with cleaning up the design elements in one of my project’s Jasper reports. Among the design changes was the request to switch the report to a new custom font. No problem I said, easy peazy.

Some 10 browser tabs and about an hour of googl’ing later I realized that this task was neither easy or peazy. As should be customary for any software developer, I’m documenting my findings with the hope that this will be the last tab someone else opens on their way to completing this task.

The basic elements of adding a custom font to a Jasper report are:

1. Go get the font files you want to use ( TTF, EOT, SVG or WOFF (OTF converted to TTF works as well))
2. Add the fonts to Jaspersoft Studio (or iReport) using the UI. Now you can preview the font in your report.
3. Export the fonts to a fonts-extention.jar file for use in your application.
4. Take care of integrating the jar into your build.

The tools I’m using are primarily Jaspersoft Studio and Maven. This tutorial covers adding fonts to Jaspersoft Studio as well as to the Java application that will be generating reports from exported jrxml template files. *note that the steps for adding fonts to Jaspersoft Studio should be similar to iReport, and the basic pattern for exporting is pretty much the same. Also note that there are a few different options for generating the required jar file and integrating it into your application, I’m going to talk about the ones that worked for me.

As mentioned above, I found a lot of resources while I was initially researching this task, but none of them covered the entire process from start to finish and most of them leave out small, but key, details. That said, if you get stuck on any of the following steps there are certainly a number of forum posts and Stack Overflow questions that can get you back on track.

Once you have your font files downloaded you’re ready to start. Open up Jaspersoft Studio (or iReport, or if you’re creating the fonts-extension.jar manually for some reason, skip to the section that applies to you):

1. Click Window\Preferences
2. In the preferences window go to Jaspersoft Studio/Fonts and click add

Jaspersoft Studio Preferences Configure Font Family window

The Jasper Reports forum page that I had initially tried to follow suggested that creating the jar manually was the only way to succeed, and that doing it through Jaspersoft Studio or iReport would cause errors. This was not good advice. If you do chose to create the jar manually, there are important details for pathing and jar structure that will be discussed in this section that may help you.

The goal of this section is to get your custom font into Jaspersoft or iReport so that you can modify your report and see how things look. I’m going to stay on task, but note that the fields in the form above also have an impact on the next section: exporting the fonts-extention.jar

Family Name

This is the name that will be used to choose the font in the report, and will also be referenced in the jrxml

Font Weight Tabs

If the custom font you are using has multiple weights, use the tabs to add a font file for each weight. A custom font can be added with just one weight.

Within each font weight tab are fields for the font file (TTF, EOF, SVG, WOFF). The font file does not have to be installed on the system. Use browse to select the file. Only one font file per tab is required, and I’m not sure why multiples are allowed.

PDF Font Name

This was the field that caused me the most trouble. As far as I can tell PDF Font Name is a terrible misnomer. This field probably should have been called “Path to Font Within fonts-extension.jar” because that’s what it actually does.

After doing all of my research, following tutorials and finally getting a properly formed fonts-extension.jar into my Java application, I kept getting Font not available to the JVM and other errors. It turns out there is a bit of a “chicken and egg” catch in this process. You have to provide a value for PDF Font Name which is a valid path to the font file in the fonts-extension.jar… but how do you know what that path should be until you have the jar?

Luckily you don’t have to, because I’m going to show you the structure of the exported jar in the next section and you can use that as an example. It would be wise to note that if the exported fonts-extension.jar is throwing errors in your application, the value of the PDF Font Name field and the structure of the jar would be good places to start troubleshooting.

PDF Encoding

There are numerous values for character encoding in this dropdown that don’t really map to traditional encoding options. This, of course, will depend on the language of the font being used and the desired encoding. The two that were most relevant to my project were:

• CP1252 (Western ANSI)
• Identity-H (basically UTF-8)

Embed this font in PDF document

Pretty self-explanatory. You probably want to do this

Click Finish

If you click next there are other fields for font-mapping (if the custom font files aren’t available for some reason), and also for locale based usage of custom fonts. While these are interesting add-ons, they are beyond the scope of this tutorial. After clicking finish the font will be available for use in the report. Try it out to make sure it’s working and that the chosen character encoding is appropriate.

The fonts-extension.jar

All of that work and we still don’t have the ability to actually use a custom font in our Java generated Jasper report. In this section I will talk about how to export the fonts-extension.jar file and add it to your project. Additionally, there will hopefully be some tidbits in here if you, or someone before you, chose to create the jar manually.

Export the jar

After testing and verifying that the custom font works in Jaspersoft Studio (or iReport), open the Font configuration preference panel again. This time we’re going to click on the font that we previously added, and then click the Export button. Chose an export location and name the file fonts-extention Jaspersoft will add the .jar for you.

Cool, now we finally have a fully configured jar file we can add to our project. Before doing that I want to take a look at the file structure.

fonts-extension.jar
    | jasperreports_extension.properties
    |
    \ — -fonts
           | fontsfamily1512493722844.xml
           |
           \ — -Febrero
                 Febrero-Light.ttf
                 Febrero-Regular.ttf

The following sections provide some background on the internals of the fonts-extension.jar. Aside from information regarding values used for pathing that need to be entered into the Jaspersoft/iReport PDF Font Name field, this information is more or less for clarity and completeness.

jasperreports_extension.properties

This file allows you to chose which factory will be used to load the fonts into the report. Note that if you are generating the fonts-extension.jar, you don’t need to do anything here. There are two options:

net.sf.jasperreports.extension.registry.factory.fonts

net.sf.jasperreports.extension.registry.factory.simple.font.families

The first option is used by JaspersoftStudio (and iReport I presume). The second option is used by JasperReports Server or any Jasper Java application that is generating reports. You can add both properties to the file without issue. There is also a third property which points to the fontsFamily xml file:

net.sf.jasperreports.extension.simple.font.families.[fontFamilyName*]

fontFamilyName is either user entered, or generated by Jaspersoft Studio/iReport. If you have chosen to export the jar file, it will be generated for you. (I couldn’t really see what this maps to in the scheme, this name might not be valuable to this process). The file will look something like the following:

Contents of jasperreports_extension.properties note the third property is a path to the fonts family xml, relative to the root of the jar

Fonts Family XML

This file stores the settings for the font and allows Jasper reports to reference the font file based on the name/weight of a given font. Below is an example of a font families XML file from an exported fonts-extension.jar.

<?xml version="1.0" encoding="UTF-8"?>
<fontFamilies>
   <fontFamily name="Febrero">
    <normal>
       <ttf><![CDATA[fonts/Febrero/Febrero-Light.ttf]]></ttf>
       <pdf><![CDATA[fonts/Febrero/Febrero-Light.ttf]]></pdf>
    </normal>
    <bold>
       <ttf><![CDATA[fonts/Febrero/Febrero-Regular.ttf]]></ttf>
       <pdf><![CDATA[fonts/Febrero/Febrero-Regular.ttf]]></pdf>
    </bold>
    <pdfEncoding><![CDATA[Cp1252]]></pdfEncoding>
    <pdfEmbedded><![CDATA[true]]></pdfEmbedded>
    <exportFonts/>
   </fontFamily>
</fontFamilies>

Note that the CDATA for the font (ttf) and pdf elements is a path to the font file relative to the root of the jar. How did that path get there? We entered it into the PDF Font Name field before we exported the jar. Intuitive right? So intuitive that I lost an hour of work, and used up what felt like half a gigabyte of RAM on browser tabs trying to figure out why the exported jar file was throwing errors in Java.

This is probably why the poster of the tutorial on the Jaspersoft Community website says not to use Jaspersoft Studio or iReport: (http://bit.ly/2B12WHa). But now that we know of this silly bug in the UI, the process of adding custom fonts can be so much easier!

Adding the Font to a Java Application

The final task to complete now that we have a properly formatted fonts-extension.jar file is to add the jar to a Java project. There are a lot of different variables here, and a lot of possible application configurations. The best I can do is tell you what worked for me and hope that you can apply it to your project.

Most of the Stack Overflow questions and tutorials I found said that all you have to do is “put the jar on your class path” I didn’t find this advice terribly helpful. If you do, then you can probably stop reading now and just go do that.

I’m working with a Java project that uses Maven, so I’ll show you how I included the fonts-extension.jar into the build. If you aren’t using Maven, then I think the basic advice you can follow is to just put the jar file where all of your other jar files are in your project so that it can be compiled. In my case I needed the jar to compile and get packaged in the target/[project]/WEB-INF/lib folder. Here are the steps to follow:

1. Copy the fonts-extension.jar into any arbitrary location in your project (for source control)
2. Add a Maven system-scoped dependency that points to the jar. Maven will do the rest when you run an install

<dependency>
    <groupId>local.jasperFontOverrides</groupId>
    <artifactId>local.jasperFontOverrides</artifactId>
    <version>1.0</version>
    <scope>system</scope>
    <systemPath>${basedir}/src/main/resources/reports/fonts-extension.jar</systemPath>
</dependency>

(I don’t believe the values of the groupId, artifactId, and version really matter for this type of dependency, I could be wrong but this code worked for me)

The Future

Quick note here. If you want to add more fonts to your project in the future, just import the fonts-extension.jar into Jaspersoft Studio or iReport, add the new font(s) and follow the steps for exporting again. This way if you are working on a team anyone can maintain the custom Jasper Reports fonts.

Conclusion

There it is, a custom font that you can use in Jaspersoft Studio, iReport, and a Java application. I hope this tutorial provides you with enough information to get custom fonts working in your project as well. Happy coding!