Skip to content

Web fonts

Jump to bottom
Andrea Campi edited this page Oct 21, 2012 · 2 revisions

Support for web fonts in Treesaver is labeled as experimental at this stage, so you may still encounter bugs. Please report them in the issue tracking and/or on the mailing list to help us improve the code.

Treesaver uses CSS to style your content; in particular, you can use the familiar font properties (font-family, font-weight and so on) to style your text. With a few caveats about the line height, this is pretty easy and will work exactly as you would expect.

You can also decide to use Web fonts to access a much wider range of typefaces. Because of the way Treesaver lays out text, you will need to do extra work to get it to work reliably.

Background information

In order to figure out how many columns are required to fit all the content, how tall and wide each will be, how many pages and which grids should be used, Treesaver sets up hidden paragraphs and other pieces of content and takes some measurements. This happens as soon as the content is loaded, and the process is done off-screen so that the users never notice. Each font has different overall metrics (how big each letter is and so on); additional features like ligatures may also affect this. As a consequence the results of this first step are strongly related to the font being used.

When it's finally time to show the content in the browser, Treesaver puts each column and each paragraph onto the screen, trusting that the metrics are still correct. Normally that assumption is true, and everything works nicely.

Webfonts however are often loaded separately. Even if they are loaded from the CDN, the browser may download them too late, and they may become available in between these two stages. This means that Treesaver will take measurements using a fallback font (or the browser's default font, if you haven't specified a fallback). Unless the two fonts have the exact same metrics, you (and your readers) will likely notice display problems:

  • if your content takes up more space when set with the web font, you may lose one or more lines of text at end of a column;
  • in other cases, a line of text at the end of a column may be repeated at the beginning of the next column;
  • figures and captions may also be affected in a number of ways.

There are a few things you can do to solve the problem:

  • use fonts that have the exact same metrics: some foundries may provide web fonts that set each letter at exactly the same size as one of the "basic" fonts.
  • embed the font in your CSS file: doing so guarantees that the web font is available when Treesaver starts its layout process, and thus reduces the problem. If you are using a commercial font, make sure your license allows this use.
  • tell Treesaver about the web font: making sure Treesaver performs the initial layout only after the fonts are available prevents the problem.

Using a font loader with Treesaver

Treesaver 0.10.0 optionally takes care of loading web fonts in a reliable way, while still falling back to system fonts.

As of Treesaver 0.10.0 Google WebFont Loader is used as the underlying mechanism, but that may change in the future.

To opt-in to the font loader, you need to declare a global variable before including treesaver.js:

    <script>
      window.treesaverFonts = { google: { families: [ 'Tangerine', 'Jim+Nightshade', 'Scada' ] } };
    </script>
    <script src="treesaver.js"></script>

The font loader supports a few different font services, the syntax to use is documented on the Google WebFont Loader page.

Loading fonts with the treesaverFonts option will make them available to the page even if you do not include the usual CSS <link> tag, as long as your visitors have JavaScript enabled. If you want visitors with older browsers (and bots) to also get the custom fonts, you should use both.

Advanced usage: specifying fallbacks

Using treesaverFonts guarantees correct layout as long as all fonts load correctly.

However, if one or more fonts fail to load or take too long, you may still have problems. To give you complete control, Treesaver adds a few extra classes to the html element, corresponding to the name of your fonts.

In the example above, assuming only the Tangerine font could be loaded, you would see:

    <html class="... ts-tangerine-active ts-jim-nightshade-inactive ts-scada-inactive">

You can use these classes in your stylesheet to only enable fonts that have downloaded correctly.

Examples

See examples/fonts to see all of the above in action.

Clone this wiki locally