Skip to content
This repository was archived by the owner on Sep 20, 2019. It is now read-only.

Commit a850f72

Browse files
notwaldorfnotwaldorf
committed
use better words about the bundles and the loader
1 parent 632ae2e commit a850f72

1 file changed

Lines changed: 41 additions & 14 deletions

File tree

‎README.md‎

Lines changed: 41 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,27 +3,54 @@ webcomponents.js
33

44
[![Build Status](https://travis-ci.org/webcomponents/webcomponentsjs.svg?branch=master)](https://travis-ci.org/webcomponents/webcomponentsjs)
55

6-
A suite of polyfills supporting the [Web Components](http://webcomponents.org) specs.
6+
A suite of polyfills supporting the [Web Components](http://webcomponents.org) specs:
77

88
- **Custom Elements**: allows authors to define their own custom tags ([spec](https://w3c.github.io/webcomponents/spec/custom/)).
99
- **HTML Imports**: a way to include and reuse HTML documents via other HTML documents ([spec](https://w3c.github.io/webcomponents/spec/imports/)).
1010
- **Shadow DOM**: provides encapsulation by hiding DOM subtrees under shadow roots ([spec](https://w3c.github.io/webcomponents/spec/shadow/)).
1111

12-
## Releases
12+
## How to use
1313

14-
Pre-built (concatenated & minified) versions of the polyfills are maintained in the [tagged versions](https://github.com/webcomponents/webcomponentsjs/releases) of this repo. There are several variants:
14+
The polyfills are built (concatenated & minified) into several bundles that target
15+
different browsers and spec readiness:
1516

16-
- `webcomponents-lite.js` includes all of the polyfills.
17-
- `webcomponents-loader.js` is a custom loader that dynamically load a minified polyfill
18-
bundle, using feature detection. The bundles that can be loaded are:
19-
- `webcomponents-hi` -- HTML Imports (needed by Safari Tech Preview)
20-
- `webcomponents-hi-ce` -- HTML Imports and Custom Elements (needed by Safari 10)
21-
- `webcomponents-hi-ce-sd` -- HTML Imports, Custom Elements and Shady DOM/CSS (needed by Safari 9, Firefox, Edge)
22-
- `webcomponents-lite` -- HTML Imports, Custom Elements, Shady DOM/CSS and generic platform polyfills (such as Template, ES6 Promise, Constructable events, etc.) (needed by Internet Explorer 11)
17+
- `webcomponents-hi` -- HTML Imports (needed by Safari Tech Preview)
18+
- `webcomponents-hi-ce` -- HTML Imports and Custom Elements (needed by Safari 10)
19+
- `webcomponents-hi-sd-ce` -- HTML Imports, Custom Elements and Shady DOM/CSS (needed by Safari 9, Firefox, Edge)
20+
- `webcomponents-sd-ce` -- Custom Elements and Shady DOM/CSS (no HTML Imports)
21+
- `webcomponents-lite` -- all of the polyfills: HTML Imports, Custom Elements, Shady DOM/CSS and generic platform polyfills (such as Template, ES6 Promise, Constructable events, etc.) (needed by Internet Explorer 11)
22+
23+
If you are only targetting a specific browser, you can just use the bundle that's
24+
needed by it; alternatively, if you're using server-side rendering, you can
25+
send the polyfill bundle that's necessary for the browser making that request.
26+
27+
## `webcomponents-loader.js`
28+
29+
Alternatively, this repo also comes with `webcomponents-loader.js`, a client-side
30+
loader that dynamically loads the correct polyfill bundle, using feature detection.
31+
Note that because the bundle will be loaded asynchronously, you should wait for the `WebComponentsReady` before you can safely assume that all the polyfills have
32+
loaded and are ready to be used (i.e. if you want to dynamically load other custom
33+
elements, etc.). Here's an example:
34+
35+
```
36+
<head>
37+
<script src="bower_components/webcomponentsjs/webcomponents-loader.js"></script>
38+
<script>
39+
// When the polyfill has loaded, lazy-load another custom element (otherwise,
40+
// if we do this before CustomElements has loaded, the element registration
41+
// will fail.)
42+
window.addEventListener('WebComponentsReady', function() {
43+
var s = document.createElement('script');
44+
s.src = 'lazy-element.js';
45+
document.head.appendChild(s);
46+
});
47+
</script>
48+
</head>
49+
```
2350

2451
## Browser Support
2552

26-
Our polyfills are intended to work in the latest versions of evergreen browsers. See below
53+
The polyfills are intended to work in the latest versions of evergreen browsers. See below
2754
for our complete browser support matrix:
2855

2956
| Polyfill | IE11+ | Chrome* | Firefox* | Safari 9+* | Chrome Android* | Mobile Safari* |
@@ -34,13 +61,13 @@ for our complete browser support matrix:
3461

3562
\*Indicates the current version of the browser
3663

37-
The polyfills may work in older browsers, however require additional polyfills (such as classList)
38-
to be used. We cannot guarantee support for browsers outside of our compatibility matrix.
64+
The polyfills may work in older browsers, however require additional polyfills (such as classList, or other [platform](https://github.com/webcomponents/webcomponents-platform)
65+
polyfills) to be used. We cannot guarantee support for browsers outside of our compatibility matrix.
3966

4067

4168
### Manually Building
4269

43-
If you wish to build the polyfills yourself, you'll need `node` and `npm` on your system:
70+
If you wish to build the bundles yourself, you'll need `node` and `npm` on your system:
4471

4572
* install [node.js](http://nodejs.org/) using the instructions on their website
4673
* use `npm` to install [gulp.js](http://gulpjs.com/): `npm install -g gulp`

0 commit comments

Comments
 (0)