Fonts

We briefly discussed Cubane’s font system as part of the Resources section. However, this section will explore the font system in more depth.

Web Fonts play an increasingly important role. Cubane provides an automatic process for including a large number of free web fonts within your websites.

Cubane provides a default font backend which is using the google-webfonts-helper by Mario Ranftl.

Declaring Font Resources

You can use any font (listed on the Google WebFonts Helper website) by simply including it as a resource within your app’s list of resources like in the following example:

RESOURCES = [
    'font|Open Sans',
    ...
]

And that’s it. In your CSS style, you can now use the font, for example:

body {
    font-family: 'Open Sans', sans-serif;
}

Cubane will automatically download all required font files to your local system and will also generate all required CSS style for the declaration of the font.

Note

When referring to fonts, make sure that the name of the font is given as listed on the Google WebFonts Helper website, otherwise, Cubane will not be able to locate the exact font.

Declaring Font Variants

A font may come in different flavours, mostly with separate boldness and italic style or not. It is important to understand that each variation of a font is ultimately a separate file that the browser needs to download if it is used on a site.

For example, if we simply specified the following font resource:

RESOURCES = [
    'font|Open Sans',
    ...
]

Then Cubane will download all available font variations for Open Sans, which would be – at the time of writing – ten different variations and therefore ten different font files. In addition, Cubane would also generate CSS style to declare all different font variants.

However, this does not necessarily mean that browsers will always download ten font files: Browsers will only download the ones that are actually needed; if your website does not make use of the italic variant in boldness 700, then the corresponding file will never be downloaded.

Browsers can also synthesise missing font declarations. For example, if a particular font is not declared, the browser may still be able to produce the required boldness and italic style automatically. Of course, the result may not be as pleasing as the actual font file itself.

In order to give you more fine-control over which font variants are declared, you can add the required font variants to the resource declaration, for example:

RESOURCES = [
    'font|Open Sans:300,300i,600,600i',
    ...
]

This will only generate the font declarations for four variants for the boldness 300 and 600, both in regular and italic styles. Cubane will also only download font files for those variants.

Font Charsets

Currently, Cubane will only download the latin charset for any font. If you require any other charset, you would need to download the required font files by yourself manually.

Supported Font File Formats

Cubane’s font system is currently only downloading two font versions: woff2 and woff. This should provide a very good coverage for all modern browsers.

Font Cache

The font system will automatically download all required font files if they are missing locally. When running

$ python manage.py runserver

Then you should see an output similar to the following:

Updating font cache...Please Wait...
Open Sans                             [CACHED]

Font files are cached within your media folder, which should be similar to:

media/fonts/open-sans/

You can delete all locally cached font files by executing the following command:

$ python manage.py clearfonts

The following command will download all font files that are missing:

$ python manage.py loadfonts

You can also do those two commands in one step if you wanted to remove all fonts and download them again:

$ python manage.py loadfonts --refresh

Note

The font cache will not download additional font versions if the font is already cached. If you add or remove font versions, the font needs to be refreshed:

$ python manage.py loadfonts --refresh

Font Backends

A font backend is a class implementation derived from :class:FontBackendBase. Its responsibility is to download a particular font given by its name if the backend knows about the font.

You can declare multiple font backends in your project settings. The default declaration only contains the default Google Font Helper Backend:

CUBANE_FONT_BACKENDS = [
    'cubane.fonts.backends.GoogleFontsBackend',
]

Feel free to add additional font backends if required. When downloading fonts, Cubane’s font system will simply try every font backend it knows about and will accept the first positive response that it can acquire. All you need to implement for a font backend to work is the following method:

def get_font(self, font_name):
    ...

Simply verify that a font with given name is available. If so, return a new instance of :class:FontDescriptor, which contains a set of details of the font. If the font is not available, simply return None.