Blog

Code Snippet: Integrate Custom Fonts into Oxygen

(2020)

Content

Task

Oxygen Builder allows you to select standard web-safe font combinations, Google Web Fonts and even TypeKit fonts.
Custom fonts, such as fonts licensed by the customer, are not available here.

Of course you can upload your own fonts to the server and then embed them by CSS yourself. But in Oxygen such a font is still not available for selection.

Official Solution - Plugin "Elegant Custom Fonts"

With the plugin "Elegant Custom Fonts" (author Louis Reingold, founder of Soflyy, the company that offers the Oxygen Builder) you can upload your own fonts and they will be available for selection in Oxygen. Perfect.

Alternative Solution - Code Snippet

For a customer project, I had to use a font licensed by the customer to comply with the CI, but I didn't want to install another plugin for just this one font.

Since I already had installed the plugin "Code Snippets" anyway in order to implement several other features in this project, I developed a solution, which can be integrated as code snippet.

For the Oxygen community I present a highly improved version of this code snippet below.

Download

The Code Snippet is available for download here:

oxygen-custom-fonts.code-snippets.json
Version 2.1.1, 2020-10-03

For installation and use of the downloaded JSON file you will need the plugin Code Snippets.
You can install the JSON file using the "Import" function of the plugin. 
Don't forget to activate the snippet after import.

New functionalities and bug fixes are documented in the history.

Description

Instructions

  1. Create a new directory wp-content/uploads/fonts
  2. Upload your font files (eot, otf, svg, ttf, woff, woff2) into this fonts directory.

The script will find all font files, make them available for selection in Oxygen and generate CSS code in the frontend.

Font Files, Names, Weights and Styles

The snippet supports the font formats EOT, OTF, SVG, TTF, WOFF, WOFF2.

The filename of the font file will be used as font name.
So for the font file "Matthias Altmann.woff" Oxygen will display the font name "Matthias Altmann".

If the file name contains keywords for font weights, these are recognized and not included in the font name, but noted in the generated CSS code accordingly.
The following weights and styles are currently recognized:

Font WeightKeywords
100Thin
200ExtraLight, UltraLight
300Light
400Normal, Regular
500Medium
600DemiBold, SemiBold
700Bold
800ExtraBold, UltraBold
900Heavy

The keywords are not case sensitive and may contain hyphens between the keyword parts.
ExtraLight is therefore recognized in the same way as extra-light.

Furthermore, the keyword "italic" is recognized for the italic font style. Also here, the capitalization and a leading hyphen are irrelevant.

If there are multiple font files with the same name but different font formats (eot, otf, svg, ttf, woff, woff2), Oxygen will display the font name only once. However, the generated CSS will contain all available font formats. The browser will choose the preferred one by itself.

Performance

While developing the script I paid a lot of attention to efficiency and performance.

  • Search for font files: ø 0.0015 sec.
  • Output of CSS code: ø 0.0002 sec.

(measurements on iMac i9 3.6 GHz, MAMP, PHP 7.4.2, about 30 font files in subdirectories)

The CSS code for the fonts is emitted at the end of each page, no matter if one of the fonts is used on that page or not.
However, the browser loads a font only when it is really needed, and then only in the one preferred format.

FAQ - Frequently Asked Questions

Why are there no font weights available for my font in Oxygen Global Settings?

In Oxygen Global Settings you can define the font weights for Google Fonts to be embedded. This way you can limit which font weights are loaded from Google Fonts Server and thus reduce the file size if only a few font weights are used.

For our own fonts, which we embed using this Code Snippet, we decide ourselves which font files we place in the "fonts" folder. Usually there is a separate font file for each font weight. All these font files provided by us and thus the different font weights are offered to the browser. However, the browser only loads the font files with the font weights that are really needed to display the page.

So there is no reason to limit the font sizes for our own fonts in the Oxygen Global Settings.

Can I host Google Fonts locally with this Code Snippet?

Yes. With caution.

My Code Snippet will search for font files and add them to the Oxygen font list. However, Oxygen offers some Google Fonts in the font list by itself.

For example, if we download the Google Font "Roboto" and host it locally, my Code Snippet will add it to the font list. Oxygen adds the Google Font "Roboto" itself. So "Roboto" is now included twice in the list: Once as local font and once as Google Font.

Even more interesting are Google Fonts with spaces in their names. The Google font "Open Sans" is given file names with "OpenSans" (without space) when downloaded. My Code Snippet adds this font as "OpenSans" to the Oxygen font list. But Oxygen itself adds the Google Font "Open Sans" (with space) to the font list.

So I do not recommend to use this Code Snippet as a solution for local hosting of Google Fonts.
On my own websites I use the fantastic plugin "Self-Hosted Google Fonts". With this I am – without the slightest effort – GDPR compliant.

Disclaimer

I have developed and tested the code snippet to the best of my knowledge under WordPress 5.5.1 and Oxygen 3.5.
I provide the code snippet for free use.
I cannot give a guarantee for the functionality in all conceivable WordPress environments.
Download and use of this code snippet is at your own risk and responsibility.

History

Version 1 (2020-04-10)

  • Initial release for customer project

Version 2.0.0 (2020-09-15) 

  • Improved version 
  • Finds all font files (eot, otf, svg, ttf, woff, woff2) in directory wp-uploads/fonts/, optionally recursive 
  • Takes font name from file name 
  • Emits optimized CSS with alternative font formats 
  • Special handling for EOT for Internet Explorer

Version 2.1.0 (2020-09-16)

  • New features:
    • Detection of font weight and style from file name 
  • Bug fixes: 
    • EOT: Typo in extension detection 
    • EOT: Missing quote in style output

Version 2.1.1 (2020-10-03)

  • Bug fixes:
    • Handle empty fonts folder correctly.
      (Thanks to Mario Peischl for reporting!)
magnifier