Thesis Fonts API

The Thesis Fonts API is a simple tool that allows users to register new fonts for use within the Thesis interface.

In addition, the registered fonts contain a CSS font-family declaration that Skin developers can reference while manipulating CSS variables.

By default, Thesis ships with support for common web-safe fonts along with some other standard fonts on Windows and Mac operating systems.

Default Web-safe Fonts

Thesis supports the following web-safe fonts by default:

  • Arial
  • Arial Black
  • Arial Narrow
  • Courier New (monospace)
  • Georgia
  • Times New Roman
  • Trebuchet MS
  • Verdana

Additional Default Fonts

In addition to the core web-safe fonts, Thesis also supports these fonts, which are commonly found on modern versions of Windows and Mac operating systems:

  • American Typewriter
  • Andale Mono (monospace)
  • Baskerville
  • Calibri
  • Cambria
  • Candara
  • Consolas (monospace)
  • Constantia
  • Corbel
  • Gill Sans
  • Helvetica
  • Hoefler Text
  • Lucida Grande
  • Menlo (monospace)
  • Monaco (monospace)
  • Palatino
  • Tahoma

Thesis Font Array Format

All fonts registered with Thesis must adhere to the Thesis font array format in order to work properly. Here’s a sample array for Arial:

'arial' => array(
	'name' => 'Arial',
	'family' => 'Arial, "Helvetica Neue", Helvetica, sans-serif',
	'mu' => 2.31)

The Thesis font list is an associative array, and each array key—in this case, 'arial'—should be reminiscent of the actual font name. The other parameters define the font itself:

  • 'name' — (required) the font name as it will appear in the Thesis interface
  • 'family' — (required) the CSS font-family declaration for this font
  • 'mu' — (optional) the character constant for this font

The first two parameters are self-explanatory, but the third, 'mu', is probably new to you. If a 'mu' value is given for a particular font, Thesis will use this value to achieve absolute precision when calculating line heights and layout spacing.

If no 'mu' value is supplied, then Thesis will approximate typographical calculations based on Georgia/Helvetica/Arial, which all have similar, median values for 'mu'.

Registering New Fonts for Use

If you’re a Skin developer and would like to register new fonts for use with your Skin, then you should use the handy fonts() method from the Skin API.

If you’re not a Skin developer but would still like to register fonts for use on your site, you’ll need to take a slightly different approach by using the thesis_fonts filter.

Here’s an example for adding Adelle from Typekit:

add_filter('thesis_fonts', 'add_my_font');
function add_my_font($fonts) {
	$fonts['adelle'] = array(
		'name' => 'Adelle',
		'family' => 'Adelle, serif');
	return $fonts;
}

Notice how the add_my_font function includes a $fonts parameter and simply adds Adelle to it—this ensures that you do not overwrite any other fonts that have been registered with Thesis.

Using the Fonts API to Determine CSS font-family

Attention! This section contains example code that is only pertinent to Skin developers.

When a font is registered with Thesis and then selected in an interface, Thesis only saves the associative array key for that font.

For example, if a user were to select the Adelle font that we registered in the sample code above, the 'adelle' array key is what would actually get saved.

However, if you’re a Skin developer who is attempting to modify CSS based on a user’s font selection, that data is useless to you. What you really need is the font stack for that font so you can output a new font-family declaration within your CSS.

Fortunately, the Skin API contains a handy method, family(), that enables you to grab a font-family when all you know is the font array key. To wit:

public function css_variables() {
	global $thesis;
	$vars['font'] = $thesis->api->fonts->family(!empty($this->design['font']) ? $this->design['font'] : 'georgia');
}

In the above code, if the user has selected a font for the 'font' option, then Thesis will store the font-family for the selected font in $vars['font'].

If the user has not selected a font, then $vars['font'] will receive the Georgia font-family by default.