Skip to content

Usage

Jump to bottom Edit New page
Simo Kinnunen edited this page Aug 13, 2012 · 60 revisions

Cufón has been designed with developers in mind. Therefore the API is simple and configuration is usually not needed at all, as most of the needed information is provided by CSS style sheets.

See API for more detailed, JavaScript-specific documentation. For experienced users only!

Prefer video? Try this helpful screencast by Jeffrey Way.

The short version

  1. Download cufon-yui.js from the cufón website and upload it to your own server.
    • If you’re upgrading, just replace your old cufon-yui.js and you’re good to go. No need to convert your fonts again.
  2. Use the font converter (generator) on the website:
    1. Choose the font file you want to convert. Try not to enter the same file multiple times.
    2. In case of multiple font files, you may want to enter the font name to the font-family text box. This helps avoid naming troubles.
    3. Check the EULA checkbox right below the file upload fields (but only if you agree, of course).
    4. The default settings are good for most people. You don’t have to modify them.
    5. At the bottom, accept the generator terms. This is different from the EULA checkbox. Both must be checked.
    6. Submit the form and you’re done! If you get an error message, read it and act accordingly.
  3. Upload the generated .font.js file to your server. You may rename the file.
  4. Your HTML should look like this: 
    <!doctype html>
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
		<title>Playing with Cufón</title>
		<!-- Stylesheets here, before all scripts. Helps avoid styling issues. -->
		<link rel="stylesheet" type="text/css" href="style.css" />
		<!--
		If you want to use complex selectors with Cufón, load a selector engine (JavaScript framework) here.
		We support jQuery, Sizzle, MooTools, Dojo, Prototype and other popular frameworks.
		-->
		<script src="cufon-yui.js" type="text/javascript"></script>
		<script src="YourFont.font.js" type="text/javascript"></script>
		<script type="text/javascript">
			Cufon.replace('h1'); // Works without a selector engine
			Cufon.replace('#sub1'); // Requires a selector engine for IE 6-7, see above
		</script>
	</head>
	<body>
		<h1>Your custom font here</h1>
		<h2 id="sub1">Your custom font here too</h2>
		<!-- To avoid delays, initialize Cufón before other scripts at the bottom -->
		<script type="text/javascript"> Cufon.now(); </script>
		<!-- Google Analytics and other scripts here -->
	</body>
</html>
  5. And you’re set! To avoid hard-to-spot issues, here are a few things to look out for in your HTML:
    • A transitional doctype will break line-height, use a strict or HTML5 doctype.
    • Avoid whitespace (or anything else for that matter) before the doctype. This has been known to affect printing in IE.
    • UTF-8 is the only supported character set. Use others at your own risk. Characters may go missing.

If you need support, we’ve got a Google Group for that, but please do try to solve the problem by yourself first. We’re busy too!

The longer version

Step 1 – Get cufón!

It is highly recommended that you always use the YUI-compressed version of cufón, available from the cufón website. Download the file and upload it to your own server.

Updating to a newer version? Just replace your old cufon-yui.js with the new one and you’re good to go. Fonts need not be converted again.

Should you experience problems or if you just want to poke around a little, you may also use the uncompressed version, available from GitHub.

Step 2 – Generate a font

You may use the font generator at our website or run a copy of your own. If you plan on going for the latter option you’re probably clever enough to figure out how to get it running – the source is available from GitHub.

The name of the resulting file will include the name of the font and the weight of the font (as a number – 400 is equivalent to “normal” and 600 means “bold”). So, for example, the bold version of Bitstream Vera Sans would result in a file called Bitstream_Vera_Sans_600.font.js. The name of the file doesn’t actually matter at all, but it makes it easier for you to identify your fonts.

Using the generator should be pretty straightforward, but ideas that enhance usability are always welcome. Please use our Google Group for that.

Step 3 – Replace text

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<script src="cufon-yui.js" type="text/javascript"></script>
		<script src="Vegur_300.font.js" type="text/javascript"></script>
		<script type="text/javascript">
			Cufon.replace('h1');
		</script>
	</head>
	<body>
		<h1>This text will be shown in Vegur.</h1>
	</body>
</html>

For the purposes of this example you may ignore everything that is not contained by <head>.

So what exactly happens here?

First, we include the YUI compressed version of cufón that you should always use.

Then we include the font that we converted in Step 2. Nothing special here, you include it just like you would any other JavaScript file. So far so good.

Then we get to the magic part. We want to replace all <h1> elements in the document. And that’s exactly what the tell cufón to do, with Cufon.replace('h1'). Nothing else is needed, cufón will use the CSS rules associated with the elements and determine what to do. You should not place Cufon.replace inside $(document).ready or similar functionality because it will make Step 4 ineffective.

In order to avoid unnecessary duplication cufón does not come bundled with a selector engine, which means that by default you’ll only be able to use tag names (such as h1) as selectors. However, cufón detects quite a few popular JavaScript frameworks (such as jQuery, MooTools, Dojo and Prototype) automatically, so if you’re using one you’ll only need to include it before cufón and things like Cufon.replace('#content > h1:first-child') and Cufon.replace('#nav a') will work just fine.

Step 4 – Make Internet Explorer behave

Unfortunately one problem remains with Internet Explorer. In most cases, there is a short but visible delay before the text is replaced. You can avoid this issue by inserting the following snippet right before the closing </body> tag (or before any external scripts such as Google Analytics):

<script type="text/javascript"> Cufon.now(); </script>

And the delay is gone. For a more in-depth example, see API.

Note: This step will hopefully become obsolete in the future.

Using multiple fonts

To use multiple fonts you only need to specify which font you want to use and you’re set:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<script src="cufon-yui.js" type="text/javascript"></script>
		<script src="Vegur_300.font.js" type="text/javascript"></script>
		<script src="Myriad_Pro_400.font.js" type="text/javascript"></script>
		<script type="text/javascript">
                        Cufon.replace('h1', { fontFamily: 'Vegur' });
			Cufon.replace('h2', { fontFamily: 'Myriad Pro' });
		</script>
	</head>
	<body>
		<h1>This text will be shown in Vegur.</h1>
		<h2>This text will be shown in Myriad Pro.</h2>
	</body>
</html>

If not specified, cufón will use the font that was loaded last (in this case it would be Myriad Pro), which is why there was no need to specify the font in the first example.

All Cufón-enabled pages must be UTF-8 encoded. Compatible encodings, such as US-ASCII, are also fine.

Add a custom footer
Add a custom sidebar
Clone this wiki locally