Skip to content

Commit 433a8cc

Browse files
author
Lucas
committed
Update README.md
1 parent 4f8b8e1 commit 433a8cc

File tree

1 file changed

+153
-121
lines changed

1 file changed

+153
-121
lines changed

‎README.md

Lines changed: 153 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -24,34 +24,38 @@ Web Font Loader gives you added control when using linked fonts via `@font-face`
2424

2525
To use the Web Font Loader library, just include it in your page and tell it which fonts to load. For example, you could load fonts from [Google Fonts](http://www.google.com/fonts/) using the Web Font Loader hosted on [Google Hosted Libraries](https://developers.google.com/speed/libraries/) using the following code.
2626

27-
<script src="//ajax.googleapis.com/ajax/libs/webfont/1.4.7/webfont.js"></script>
28-
<script>
29-
WebFont.load({
30-
google: {
31-
families: ['Droid Sans', 'Droid Serif']
32-
}
33-
});
34-
</script>
27+
```html
28+
<script src="//ajax.googleapis.com/ajax/libs/webfont/1.4.7/webfont.js"></script>
29+
<script>
30+
WebFont.load({
31+
google: {
32+
families: ['Droid Sans', 'Droid Serif']
33+
}
34+
});
35+
</script>
36+
```
3537

3638
Alternatively, you can link to the latest `1.x` version of the Web Font Loader by using `//ajax.googleapis.com/ajax/libs/webfont/1/webfont.js` as the `script` source. Note that the version in this url is less specific. It will always load the latest `1.x` version, but it also has a shorter cache time to ensure that your page gets updates in a timely manner. For performance reasons, we recommend using an explicit version number (such as `1.4.7`) in urls when using the Web Font Loader in production. You can manually update the Web Font Loader version number in the url when you want to adopt a new version.
3739

3840
It is also possible to use the Web Font Loader asynchronously. For example, to load [Typekit](http://www.typekit.com) fonts asynchronously, you could use the following code.
3941

40-
<script>
41-
WebFontConfig = {
42-
typekit: { id: 'xxxxxx' }
43-
};
44-
45-
(function() {
46-
var wf = document.createElement('script');
47-
wf.src = ('https:' == document.location.protocol ? 'https' : 'http') +
48-
'://ajax.googleapis.com/ajax/libs/webfont/1.4.7/webfont.js';
49-
wf.type = 'text/javascript';
50-
wf.async = 'true';
51-
var s = document.getElementsByTagName('script')[0];
52-
s.parentNode.insertBefore(wf, s);
53-
})();
54-
</script>
42+
```html
43+
<script>
44+
WebFontConfig = {
45+
typekit: { id: 'xxxxxx' }
46+
};
47+
48+
(function() {
49+
var wf = document.createElement('script');
50+
wf.src = ('https:' == document.location.protocol ? 'https' : 'http') +
51+
'://ajax.googleapis.com/ajax/libs/webfont/1.4.7/webfont.js';
52+
wf.type = 'text/javascript';
53+
wf.async = 'true';
54+
var s = document.getElementsByTagName('script')[0];
55+
s.parentNode.insertBefore(wf, s);
56+
})();
57+
</script>
58+
```
5559

5660
Using the Web Font Loader asynchronously avoids blocking your page while loading the JavaScript. Be aware that if the script is used asynchronously, the rest of the page might render before the Web Font Loader is loaded and executed, which can cause a [Flash of Unstyled Text (FOUT)](http://help.typekit.com/customer/portal/articles/6852).
5761

@@ -74,35 +78,41 @@ Web Font Loader provides an event system that developers can hook into. It gives
7478

7579
CSS events are implemented as classes on the `html` element. The following classes are set on the `html` element:
7680

77-
.wf-loading
78-
.wf-active
79-
.wf-inactive
80-
.wf-<familyname>-<fvd>-loading
81-
.wf-<familyname>-<fvd>-active
82-
.wf-<familyname>-<fvd>-inactive
81+
```css
82+
.wf-loading
83+
.wf-active
84+
.wf-inactive
85+
.wf-<familyname>-<fvd>-loading
86+
.wf-<familyname>-<fvd>-active
87+
.wf-<familyname>-<fvd>-inactive
88+
```
8389

8490
The `<familyname>` placeholder will be replaced by a sanitized version of the name of each font family. Spaces and underscores are removed from the name, and all characters are converted to lower case. For example, `Droid Sans` becomes `droidsans`. The `<fvd>` placeholder is a [Font Variation Description](https://github.com/typekit/fvd). Put simply, it's a shorthand for describing the style and weight of a particular font. Here are a few examples:
8591

86-
/* n4 */
87-
@font-face { font-style: normal; font-weight: normal; }
92+
```css
93+
/* n4 */
94+
@font-face { font-style: normal; font-weight: normal; }
8895

89-
/* i7 */
90-
@font-face { font-style: italic; font-weight: bold; }
96+
/* i7 */
97+
@font-face { font-style: italic; font-weight: bold; }
98+
```
9199

92100
Keep in mind that `font-weight: normal` maps to `font-weight: 400` and `font-weight: bold` maps to `font-weight: 700`. If no style/weight is specified, the default `n4` (`font-style: normal; font-weight: normal;`) will be used.
93101

94102
If fonts are loaded multiple times on a single page, the CSS classes continue to update to reflect the current state of the page. The global `wf-loading` class is applied whenever fonts are being requested (even if other fonts are already active or inactive). The `wf-inactive` class is applied only if none of the fonts on the page have rendered. Otherwise, the `wf-active` class is applied (even if some fonts are inactive).
95103

96104
JavaScript events are implemented as callback functions on the `WebFontConfig` configuration object.
97105

98-
WebFontConfig = {
99-
loading: function() {},
100-
active: function() {},
101-
inactive: function() {},
102-
fontloading: function(familyName, fvd) {},
103-
fontactive: function(familyName, fvd) {},
104-
fontinactive: function(familyName, fvd) {}
105-
};
106+
```javascript
107+
WebFontConfig = {
108+
loading: function() {},
109+
active: function() {},
110+
inactive: function() {},
111+
fontloading: function(familyName, fvd) {},
112+
fontactive: function(familyName, fvd) {},
113+
fontinactive: function(familyName, fvd) {}
114+
};
115+
```
106116

107117
The `fontloading`, `fontactive` and `fontinactive` callbacks are passed the family name and font variation description of the font that concerns the event.
108118

@@ -112,25 +122,29 @@ Since the Internet is not 100% reliable, it's possible that a font will fail to
112122

113123
You can change the default timeout by using the `timeout` option on the `WebFontConfig` object.
114124

115-
WebFontConfig = {
116-
google: {
117-
families: ['Droid Sans']
118-
},
119-
timeout: 2000 // Set the timeout to two seconds
120-
};
125+
```javascript
126+
WebFontConfig = {
127+
google: {
128+
families: ['Droid Sans']
129+
},
130+
timeout: 2000 // Set the timeout to two seconds
131+
};
132+
```
121133

122134
The timeout value should be in milliseconds, and defaults to 5000 milliseconds (5 seconds) if not supplied.
123135

124136
### Iframes
125137

126138
Usually, it's easiest to include a copy of Web Font Loader in every window where fonts are needed, so that each window manages its own fonts. However, if you need to have a single window manage fonts for multiple same-origin child windows or iframes that are built up using JavaScript, Web Font Loader supports that as well. Just use the optional `context` configuration option and give it a reference to the target window for loading:
127139

128-
WebFontConfig = {
129-
google: {
130-
families: ['Droid Sans']
131-
},
132-
context: frames['my-child']
133-
};
140+
```javascript
141+
WebFontConfig = {
142+
google: {
143+
families: ['Droid Sans']
144+
},
145+
context: frames['my-child']
146+
};
147+
```
134148

135149
This is an advanced configuration option that isn't needed for most use cases.
136150

@@ -148,41 +162,45 @@ You can specify a specific font variation or set of variations to load and watch
148162
by appending the variations separated by commas to the family name separated by
149163
a colon. Variations are specified using [FVD notation](https://github.com/typekit/fvd).
150164

151-
WebFontConfig = {
152-
custom: {
153-
families: ['My Font', 'My Other Font:n4,i4,n7'],
154-
urls: ['/fonts.css']
155-
}
156-
};
165+
```javascript
166+
WebFontConfig = {
167+
custom: {
168+
families: ['My Font', 'My Other Font:n4,i4,n7'],
169+
urls: ['/fonts.css']
170+
}
171+
};
172+
```
157173

158174
In this example, the `fonts.css` file might look something like this:
159175

160-
@font-face {
161-
font-family: 'My Font';
162-
src: ...;
163-
}
164-
@font-face {
165-
font-family: 'My Other Font';
166-
font-style: normal;
167-
font-weight: normal; /* or 400 */
168-
src: ...;
169-
}
170-
@font-face {
171-
font-family: 'My Other Font';
172-
font-style: italic;
173-
font-weight: normal; /* or 400 */
174-
src: ...;
175-
}
176-
@font-face {
177-
font-family: 'My Other Font';
178-
font-style: normal;
179-
font-weight: bold; /* or 700 */
180-
src: ...;
181-
}
176+
```css
177+
@font-face {
178+
font-family: 'My Font';
179+
src: ...;
180+
}
181+
@font-face {
182+
font-family: 'My Other Font';
183+
font-style: normal;
184+
font-weight: normal; /* or 400 */
185+
src: ...;
186+
}
187+
@font-face {
188+
font-family: 'My Other Font';
189+
font-style: italic;
190+
font-weight: normal; /* or 400 */
191+
src: ...;
192+
}
193+
@font-face {
194+
font-family: 'My Other Font';
195+
font-style: normal;
196+
font-weight: bold; /* or 700 */
197+
src: ...;
198+
}
199+
```
182200

183201
Alternatively, you can load your fonts from a stylesheet not specified in WebFontConfig. As long as the names match those that are declared in the `families` array, the proper loading classes will be applied to the html element.
184202

185-
```
203+
```html
186204
<script src="//ajax.googleapis.com/ajax/libs/webfont/1.4.7/webfont.js"></script>
187205
<script>
188206
WebFont.load({
@@ -202,70 +220,82 @@ Alternatively, you can load your fonts from a stylesheet not specified in WebFon
202220

203221
The custom module also supports customizing the test strings that are used to determine whether or not a font has loaded. This can be used to load fonts with custom subsets or glyphs in the private use unicode area.
204222

205-
WebFontConfig = {
206-
custom: {
207-
families: ['My Font'],
208-
testStrings: {
209-
'My Font': '\uE003\uE005'
210-
}
211-
}
212-
};
223+
```javascript
224+
WebFontConfig = {
225+
custom: {
226+
families: ['My Font'],
227+
testStrings: {
228+
'My Font': '\uE003\uE005'
229+
}
230+
}
231+
};
232+
```
213233

214234
Tests strings should be specified on a per font basis and contain at least one character. If not specified the default test string (`BESbswy`) is used.
215235

216236
### Fontdeck
217237

218238
To use the [Fontdeck](http://fontdeck.com/) module, specify the ID of your website. You can find this ID on the website page within your account settings.
219239

220-
WebFontConfig = {
221-
fontdeck: {
222-
id: 'xxxxx'
223-
}
224-
};
240+
```javascript
241+
WebFontConfig = {
242+
fontdeck: {
243+
id: 'xxxxx'
244+
}
245+
};
246+
```
225247

226248
### Fonts.com
227249

228250
When using [Fonts.com web fonts](http://webfonts.fonts.com/) specify your Project ID.
229251

230-
WebFontConfig = {
231-
monotype: {
232-
projectId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
233-
version: 12345 // (optional, flushes the CDN cache)
234-
}
235-
};
252+
```javascript
253+
WebFontConfig = {
254+
monotype: {
255+
projectId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
256+
version: 12345 // (optional, flushes the CDN cache)
257+
}
258+
};
259+
```
236260

237261
The Fonts.com module has an optional `version` option which acts as a cache-buster.
238262

239263
### Google
240264

241265
Using [Google's Font API](https://code.google.com/apis/webfonts/docs/getting_started.html), name the font families you'd like to load. You can use the same [syntax](https://developers.google.com/fonts/docs/getting_started#Syntax) as in the Font API to specify styles:
242266

243-
WebFontConfig = {
244-
google: {
245-
families: ['Droid Sans', 'Droid Serif:bold']
246-
}
247-
};
267+
```javascript
268+
WebFontConfig = {
269+
google: {
270+
families: ['Droid Sans', 'Droid Serif:bold']
271+
}
272+
};
273+
```
248274

249275
You can also supply the `text` parameter to perform character subsetting:
250276

251-
WebFontConfig = {
252-
google: {
253-
families: ['Droid Sans', 'Droid Serif'],
254-
text: 'abcdedfghijklmopqrstuvwxyz!'
255-
}
256-
};
277+
```javascript
278+
WebFontConfig = {
279+
google: {
280+
families: ['Droid Sans', 'Droid Serif'],
281+
text: 'abcdedfghijklmopqrstuvwxyz!'
282+
}
283+
};
284+
```
257285

258286
The `text` subsetting functionality is only available for the Google module.
259287

260288
### Typekit
261289

262290
When using [Typekit](http://www.typekit.com), specify the Kit to retrieve by its ID. You can find the Kit ID within Typekit's Kit Editor interface.
263291

264-
WebFontConfig = {
265-
typekit: {
266-
id: 'xxxxxx'
267-
}
268-
};
292+
```javascript
293+
WebFontConfig = {
294+
typekit: {
295+
id: 'xxxxxx'
296+
}
297+
};
298+
```
269299

270300
**FYI:** Typekit's own JavaScript is built using the Web Font Loader library and already provides all of the same font event functionality. If you're using Typekit, you should use their embed codes directly unless you also need to load web fonts from other providers on the same page.
271301

@@ -281,10 +311,12 @@ For fonts loaded from supported providers, the `fontactive` event will be trigge
281311

282312
For example:
283313

284-
WebFontConfig = {
285-
providerA: 'Family1',
286-
providerB: 'Family2'
287-
};
314+
```javascript
315+
WebFontConfig = {
316+
providerA: 'Family1',
317+
providerB: 'Family2'
318+
};
319+
```
288320

289321
If `providerA` can serve fonts to a browser, but `providerB` cannot, The `fontinactive` event will be triggered for `Family2`. The `fontactive` event will be triggered for `Family1` once it loads, as will the `active` event.
290322

0 commit comments

Comments
 (0)