Permalink
Browse files

events and transitions docs

  • Loading branch information...
1 parent 01bb4cc commit f3b95fbf50462d0509de0aab82267ba3afe5b001 @rcarver rcarver committed May 6, 2010
Showing with 202 additions and 0 deletions.
  1. +5 −0 README.md
  2. +94 −0 docs/EVENTS.md
  3. +103 −0 docs/TRANSITIONS.md
View
@@ -4,6 +4,11 @@ WebFont JS gives you added control when using linked fonts via `@font-face`.
It provides a common interface to loading fonts regardless of the source, then
adds a standard set of events you may use to control the loading experience.
+Learn more:
+
+* [Events](https://github.com/typekit/webfontjs/blob/master/docs/EVENTS.md)
+* [Transitions](https://github.com/typekit/webfontjs/blob/master/docs/TRANSITIONS.md)
+
## Authors
* Ryan Carver / ryan@typekit.com
View
@@ -0,0 +1,94 @@
+# Events
+
+WebFont JS provides an event system that developers can hook into. It gives
+you notifications of the font loading sequence in both CSS and JavaScript.
+
+## The Events
+
+ * `Loading` - This event is triggered when all fonts have been requested.
+ * `Active` - This event is triggered when all of the fonts have rendered.
+ * `Inactive` - This event is triggered when the browser does not support linked fonts.
+ * `Family Loading` - This event is triggered once for each family that's loaded.
+ * `Family Active` - This event is triggered once for each family that renders.
+ * `Family Inactive` - This event is triggered if the font.
+
+### CSS Flavored
+
+CSS events are implemented as classes on the `html` element.
+
+ html.wf-loading
+ html.wf-active
+ html.wf-inactive
+ html.wf-FAMILYNAME-loading
+ html.wf-FAMILYNAME-active
+ html.wf-FAMILYNAME-inactive
+
+`FAMILYNAME` is a sanitized version of the name of each font family. In most
+cases, spaces and underscores are removed from the name. For example, `Droid
+Sans` becomes `DroidSans`.
+
+### JavaScript Flavored
+
+JavaScript events are implemented as callback functions on the `WebFont.load`
+function.
+
+ WebFont.load({
+ loading: function() {
+ },
+ active: function() {
+ },
+ inactive: function() {
+ },
+ familyloading: function(familyName) {
+ },
+ familyactive: function(familyName) {
+ },
+ familyinactive: function(familyName) {
+ }
+ })
+
+
+## Error Handling
+
+### Timeouts
+
+Since the Internet is not 100% reliable, it's possible that a font fails to
+load. You can use events to gracefully degrade in this situation.
+
+> The `Family Inactive` event will be triggered after 5 seconds if the font
+fails to render. If *at least* one font succesfully renders, the `Active`
+event will be triggered, else the `Inative` even will be triggered.
+
+### Browser Support
+
+Every web browser has varying levels of support for fonts linked via
+@font-face.
+
+> If WebFont JS determines that the current browser does not support
+`@font-face`, the `Inactive` event will be triggered.
+
+When loading fonts from multiple providers, each provider may or may not
+support a given browser.
+
+> If WebFont JS determines that the current browser can support
+`@font-face`, and *at least* one provider is able to serve fonts,
+the fonts from that provide will be loaded. When finished, the `Active` event
+will be triggered.
+
+> For fonts loaded from supported providers, the `Family Active` event will be
+triggered. For fonts loaded from a provider that *does not* support the current
+browser, the `Family Inactive` event will be triggered.
+
+For example:
+
+ WebFont.load({
+ providerA: 'Font1'
+ providerB: 'Font2'
+ });
+
+> If `providerA` can serve fonts to a browser, but `providerB` cannot, The
+`Family Inactive` event will be triggered for `Font2`. The `Family Active`
+event will be triggered for `Font1` once it loads, as will the `Active`
+event.
+
+
View
@@ -0,0 +1,103 @@
+# Transitions
+
+In order to support smooth transitions between webfont providers, WebFont JS
+provides a common interface to each provider. It also makes it trivial to load
+fonts from multiple providers.
+
+This is especially powerful when building your page against the [events][]
+because the same events are triggered regardless of the provider.
+
+Here are a few scenarios.
+
+## From Google Fonts to Typekit
+
+### Step 1: Use Google with WebFont JS
+
+You can get started with web fonts quickly and easily by just using Google.
+
+ <script type="text/javascript" src="http://www.google.com/jsapi"></script>
+ <script type="text/javascript">
+ WebFont.load({
+ google: {
+ family: ['Droid Sans']
+ }
+ });
+ </script>
+
+### Step 2: Add Typekit
+
+If you discover that Google doesn't have your preferred typeface, you may wish
+to add fonts from Typekit.
+
+(first sign up Typekit, adds font and retrieve your Kit ID)
+
+ <script type="text/javascript" src="http://www.google.com/jsapi"></script>
+ <script type="text/javascript">
+ WebFont.load({
+ google: {
+ family: ['Droid Sans']
+ },
+ typekit: 'abc1def'
+ });
+ </script>
+
+### Step 3 Remove Google
+
+You may now discover that the number of HTTP requests has increased by pulling
+fonts from both Google and Typekit. Since Typekit has all of the fonts that
+Google has, let's drop that dependency.
+
+(first add 'Droid Sans' to your Kit with ID 'abc1def')
+
+ <script type="text/javascript" src="http://www.google.com/jsapi"></script>
+ <script type="text/javascript">
+ WebFont.load({
+ typekit: 'abc1def'
+ });
+ </script>
+
+### Step 4: Remove WebFont JS
+
+You may wish to reduce HTTP requests further by dropping the dependency on the
+WebFont API and work directly with Typekit. Typekit's API is fully compatible
+with WebFont JS.
+
+ <script type="text/javascript" src="http://use.typekit.com/abc1def.js"></script>
+ <script type="text/javascript">
+ WebFont.load();
+ </script>
+
+Or as pure Typekit
+
+ <script type="text/javascript" src="http://use.typekit.com/abc1def.js"></script>
+ <script type="text/javascript">
+ Typekit.load();
+ </script>
+
+
+## Add events to self-hosted fonts
+
+### Step 1: Link to your own stylesheet
+
+If you already have fonts and the `@font-face` rules written, you might
+already be using them in your page.
+
+ <link type="text/css" rel="stylesheet" href="/fonts.css">
+
+### Step 2: Use WebFont JS
+
+To add [events][] support, use the `default` module to load your stylesheet,
+and name the font families that the stylesheet provides.
+
+ <script type="text/javascript" src="http://www.google.com/jsapi"></script>
+ <script type="text/javascript">
+ WebFont.load({
+ default: {
+ families: ['My Font'],
+ urls: ['/fonts.css']
+ }
+ });
+ </script>
+
+
+[events]: EVENTS.md

0 comments on commit f3b95fb

Please sign in to comment.