-
Notifications
You must be signed in to change notification settings - Fork 237
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');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.
<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.
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.
$('id').set('load', { onSuccess: Cufon.refresh }).load('/feed');
$('selector').load('/feed', Cufon.refresh);
$(document).ajaxSuccess(function() {
Cufon.refresh();
});
Cufon.replace('h1', {
textShadow: '1px 1px rgba(0, 0, 0, 0.2)'
});
// ..
$('#page').load('content.html', function() {
Cufon.refresh('h1');
});
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.
Cufon.replace('#message');
Cufon.replace('h2');
Cufon.replace('#content > h3');
Cufon.replace(document.getElementsByTagName('h2'));Cufon.DOM.ready(function() {
Cufon.replace(document.getElementsByTagName('h2'));
});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. Note: the hover option cannot be added to an element that has been replaced before. To make it work you must reverse the order of your replace calls (i.e. hover calls must go first). | true, false, Object | false |
| hoverables | Defines which elements :hover is used with. Defaults to links only as IE6 can’t handle anything else. | { tag: true, .. } | { a: true } |
| ignoreClass | Allows you to ignore elements based on a single or multiple class names. If an element matches one of the class names, it will not be processed by Cufón. Its children will be left alone too. (since: 1.10) | ‘nocufon’, ‘nocufon skipcufon’ | null |
| letterSpacing | The space between letters, in addition to kerning (if enabled). Defined in CSS. | ‘-1px’, .. | Defined in CSS |
| modifyText | A callback function that runs before a piece of text is replaced for the first time. Must return a new string, which will then be rendered in place of the old value. Receives four arguments: textString, textNode, element and options. (since: 1.10) | function | null |
| onAfterReplace | A callback function that runs after an element has been replaced. Receives two arguments: element and options. Child elements trigger this callback too. (since: 1.10) | function | null |
| onBeforeReplace | A callback function that runs before an element gets replaced. Receives two arguments: element and options. Child elements trigger this callback too. (since: 1.10) | function | null |
| 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’ |
| softHyphens | Whether soft hyphens are enabled or not. Note that soft hyphens inside invisible (display: none) content are not supported because their coordinates cannot be calculated. (since: 1.10) |
true, false | true |
| 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 |
| trim | If ‘simple’, trims all preceding and following whitespace in adjacent text nodes. If ‘advanced’, attempts to be more intelligent (i.e. does not simply remove everything). Note that ‘simple’ can be too simple, and ‘advanced’ not intelligent enough. Whitespace problems can usually be fixed by using a less greedy selector (e.g. Cufon.replace('body') is very bad, Cufon.replace('h1') much better). (since: 1.10) |
‘simple’, ‘advanced’ | ‘advanced’ |
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)'
}
});
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');