Every repository with this icon (
) is private.
Every repository with this icon (
) is public.
API
The Cufón API is simple yet powerful. We aim to keep it 100% backwards-compatible to make updating as painless as possible; just replace your old cufon-yui.js with a new one and you’re good to go.
All API methods return the Cufon object, which means that it’s possible to chain them. For example, the following is completely legal:
Cufon.set('fontFamily', 'Amaze').replace('h1')('h2');Cufon.now()
Tells Cufón that the DOM is ready and it’s OK to start replacing stuff. Needed for Internet Explorer, otherwise there will likely be a short delay before Cufón does its thing. Applies to other browsers as well in case you’ve got any external scripts in the <body> of the document.
Should be placed at the bottom of the HTML document, usually right before the closing </body> tag. If you’ve got external scripts (such as Google Analytics) already there, Cufon.now() should go before them.
Using Cufon.now() with Google Analytics
<script type="text/javascript"> Cufon.now(); </script>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("your-analytics-code");
pageTracker._trackPageview();
} catch(err) {}</script>
</body>
</html>
See Special cases at Styling for alternative solutions.
Cufon.refresh([selector, ..])
If given one or more selectors, repeats Cufon.replace() calls with the matching selectors. Otherwise repeats all Cufon.replace() calls. Useful if you’ve got Ajax content that needs Cufón, or if text size has changed.
Remembers options that were used with the original Cufon.replace() call.
Replacing Ajax content with MooTools
$('id').set('load', { onSuccess: Cufon.refresh }).load('/feed');
Replacing Ajax content with jQuery
$('selector').load('/feed', Cufon.refresh);
Refreshing a limited selection
Cufon.replace('h1', {
textShadow: '1px 1px rgba(0, 0, 0, 0.2)'
});
// ..
$('#page').load('content.html', function() {
Cufon.refresh('h1');
});
Cufon.replace(selector[, options])
Well, does the obvious. Also, calling Cufon() is equivalent to using Cufon.replace(), i.e. Cufon('h1') is the same as Cufon.replace('h1').
selector can be either a CSS selector (assuming you’ve loaded a compatible selector engine), an element or a collection of elements.
Using Cufon.replace() with CSS selectors
Cufon.replace('#message');
Cufon.replace('h2');
Cufon.replace('#content > h3');
Using Cufon.replace() with DOM methods (assumes that the DOM is ready)
Cufon.replace(document.getElementsByTagName('h2'));Using Cufon.replace() with DOM methods (when it is unknown whether the DOM is ready)
Cufon.DOM.ready(function() {
Cufon.replace(document.getElementsByTagName('h2'));
});Options
options is a JavaScript object containing special instructions for Cufón. The options are listed below.
| Option | Description | Possible values | Default value |
|---|---|---|---|
| autoDetect | If true, font-family is read from CSS instead of the fontFamily option. Does not work in Opera, which is why the option is disabled by default. (since: 1.04) | true, false | false |
| color | The color of the text. Defined in CSS, unless you’re using gradients (see Styling for more information). | ‘red’, ‘#f62315’, .. | Defined in CSS |
| fontFamily | The name of the font you’d like to use. Defaults to the name of the font that was loaded last (i.e. last <script>). |
Name of any loaded font | The name of the last font |
| fontSize | The size of the font. Defined in CSS, you should not touch this value. Only use pixel values if you do. | ‘14px’, ‘24px’, ‘72px’, .. | Defined in CSS |
| fontStretch | CSS3, cannot be defined in CSS. Goes against the specs by stretching the original font instead of choosing a suitable stretched variant. See all possible values and what they map to. | ‘160%’, ‘condensed’, ‘semi-expanded’, .. | ‘normal’ |
| fontStyle | The style of the font. Defined in CSS, the best match is chosen by default. | ‘normal’, ‘italic’, ‘oblique’ | Defined in CSS |
| fontWeight | The weight of the font. Defined in CSS. The best match is chosen by default. You might have to adjust this value for rarer weights if you’re using multiple variants of a font. | 100-900, ‘normal’, ‘bold’ | Defined in CSS |
| forceHitArea | Fixes hit area for mouse events in Internet Explorer. Enabling hover also enabled this option. | true, false | false |
| hover | Whether or not :hover is enabled. For performance reasons this option disabled by default. If an Object, :hover will be enabled and the values of the object will override normal options on :hover. See below for an example. | true, false, Object | false |
| hoverables | Defines which elements :hover is used with. Defaults to links only as IE6 can’t handle anything else. | |
|
| letterSpacing | The space between letters, in addition to kerning (if enabled). Defined in CSS. | ‘-1px’, .. | Defined in CSS |
| selector | The selector engine to use. Defaults to the selector engine of whatever framework you’re using, or document.getElementsByTagName otherwise. |
JavaScript function | Provided by the JS framework |
| separate | How to separate pieces of text. By default each word is considered a unit of its own, which works well with multi-line text. ‘none’ is only suitable for single lines of text. | ‘words’, ‘none’ or ‘characters’ | ‘words’ |
| textShadow | Renders text shadows. See Styling for examples. Can be defined in CSS but many browsers do not support it. | ‘1px 1px #000’, .. | ‘none’ |
| textTransform | How to transform the text. Defined in CSS. | ‘uppercase’, ‘lowercase’, ‘capitalize’, ‘none’ | Defined in CSS |
Using options with Cufon.replace()
Cufon.replace('h1', {
color: '-linear-gradient(white, black)',
fontFamily: 'Scriptina',
textShadow: '1px 1px rgba(0, 0, 0, 0.2)'
});
Cufon.replace('#nav a', {
hover: true
});
Cufon('#content h2', {
color: '-linear-gradient(#b7dded, 0.2=#70ceef, 0.5=#20b4e2, #b1dbeb)',
hover: {
textShadow: '2px 2px red',
color: '-linear-gradient(black, white)'
}
});
Cufon.set(option, value)
Sets the default value for an option. For example, you might want to do the following:
Cufon.set('fontFamily', 'Nifty Font');
Cufon.replace('#welcome');
Cufon.replace('#sidebar h2');
Cufon.replace('#content .title');
Cufon.set('fontFamily', 'Another Nice Font');
Cufon.replace('h4');
Cufon.replace('.quote');
Cufon.replace('#message');
