Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
218 lines (132 sloc) 5.79 KB
.. _topics/fonts:
=====
Fonts
=====
We briefly discussed Cubane's font system as part of the
:ref:`topics/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 <https://google-webfonts-helper.herokuapp.com/fonts>`_
by Mario Ranftl.
.. _topics/fonts/declaring_fonts:
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:
.. code-block:: python
RESOURCES = [
'font|Open Sans',
...
]
And that's it. In your CSS style, you can now use the font, for example:
.. code-block:: css
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.
.. _topics/fonts/declaring_variants:
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:
.. code-block:: python
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:
.. code-block:: python
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.
.. _topics/fonts/charsets:
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.
.. _topics/fonts/file_formats:
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.
.. _topics/fonts/cache:
Font Cache
==========
The font system will automatically download all required font files if they are
missing locally. When running
.. code-block:: console
$ python manage.py runserver
Then you should see an output similar to the following:
.. parsed-literal::
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:
.. code-block:: console
$ python manage.py clearfonts
The following command will download all font files that are missing:
.. code-block:: console
$ 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:
.. code-block:: console
$ 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:
.. code-block:: console
$ python manage.py loadfonts --refresh
.. _topics/fonts/backends:
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:
.. code-block:: python
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:
.. code-block:: python
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``.