$fonts

The $fonts object is a simple tool that handles fonts within Thesis. With it, you can:

  • Register new fonts for use with the thesis_fonts array filter
  • Access font-family declarations for use in CSS with the family() method

Any fonts registered with the $fonts object will appear in font <select> elements in the Design Options.

In addition, the registered fonts contain a CSS font-family declaration that Skin developers can reference in the css_variables() method.

By default, the $fonts object includes common web-safe fonts along with standard fonts for Windows and Mac operating systems. Here’s the entire list of default fonts included in the $fonts object.

Optional Google Fonts $functionality adds all Google Fonts that come with 400, 400 italic, and 700 weights.

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 array 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 you do not overwrite any other fonts that have been registered with Thesis.

In the next section, we’ll take a closer look at the array format used to register fonts with Thesis.

Thesis Font Array Format

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

'Arial' => array(
	'name' => 'Arial',
	'family' => 'Arial, "Helvetica Neue", Helvetica, sans-serif',
	'mu' => 2.31)
  • 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, the $typography object will use this value to achieve absolute precision when calculating line heights and layout spacing.

If no mu value is supplied, then the $typography object will approximate typographical calculations based on Georgia/Helvetica/Arial, which all have similar, median values for mu (between 2.15 and 2.35).

Using the $fonts Object to Output font-family in CSS

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

When a font is registered with Thesis and then selected in the Design Options, 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.

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 the appropriate font-family declaration in your CSS.

Fortunately, the $fonts object contains a handy method, family(), that enables you to grab a font-family when all you know is the font array key.

In the following example, we’ll assign a font-family to a CSS Variable inside the css_variables() method:

public function css_variables() {
	$vars['font'] = $this->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.