@theoplayer/web-ui 1.0.0 → 1.1.0

package/README.md

@@ -10,9 +10,9 @@ the [THEOplayer Web SDK](https://www.theoplayer.com/product/theoplayer).
 > **Note**
 > This project is under active development. While we believe it's ready for use in production, not all features are available in this first release. If you find a problem or have an idea for a new feature, don't hesitate to [open an issue](https://github.com/THEOplayer/web-ui/issues)!
 
-| ![Screenshot on desktop](./docs/assets/screenshot-desktop.png) | ![Screenshot on mobile](./docs/assets/screenshot-mobile.png) |
-| :------------------------------------------------------------: | :----------------------------------------------------------: |
-|                            Desktop                             |                            Mobile                            |
+| ![Screenshot on desktop](https://raw.githubusercontent.com/THEOplayer/web-ui/v1.0.0/docs/assets/screenshot-desktop.png) | ![Screenshot on mobile](https://raw.githubusercontent.com/THEOplayer/web-ui/v1.0.0/docs/assets/screenshot-mobile.png) |
+| :---------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------: |
+|                                                         Desktop                                                         |                                                        Mobile                                                         |
 
 ## Motivation
 
@@ -27,29 +27,27 @@ The current THEOplayer Web SDK comes with a built-in UI based on [video.js](http
 
 ## Installation
 
-This project requires the THEOplayer Web SDK to be installed.
-
-```sh
-npm install theoplayer @theoplayer/web-ui
-```
-
-You can also install a different variant of the THEOplayer npm package if you don't need all features, as long as it's aliased as `theoplayer`.
-
-```sh
-npm install theoplayer@npm:@theoplayer/basic-hls
-npm install @theoplayer/web-ui
-```
-
-Then add `@theoplayer/web-ui` to your app:
-
--   Option 1: in your HTML.
-    ```html
-    <script src="/path/to/node_modules/@theoplayer/web-ui/dist/THEOplayerUI.js"></script>
+1. This project requires the THEOplayer Web SDK to be installed.
+    ```sh
+    npm install theoplayer
     ```
--   Option 2: in your JavaScript.
-    ```js
-    import * as THEOplayerUI from '@theoplayer/web-ui';
+    You can also install a different variant of the THEOplayer npm package if you don't need all features, as long as it's aliased as `theoplayer`.
+    ```sh
+    npm install theoplayer@npm:@theoplayer/basic-hls
+    ```
+2. Install the THEOplayer Web UI.
+    ```sh
+    npm install @theoplayer/web-ui
     ```
+3. Add `@theoplayer/web-ui` to your app:
+    - Option 1: in your HTML.
+        ```html
+        <script src="/path/to/node_modules/@theoplayer/web-ui/dist/THEOplayerUI.js"></script>
+        ```
+    - Option 2: in your JavaScript.
+        ```js
+        import { DefaultUI } from '@theoplayer/web-ui';
+        ```
 
 > **Warning**
 > THEOplayer Web SDK currently only supports being loaded through a regular `<script>` tag or as a [UMD module](https://github.com/umdjs/umd), and does not support being `import`ed as a native JavaScript module. If you use `import` with THEOplayer Web UI, make sure to use a JavaScript bundler such as Webpack or Rollup to include THEOplayer in your app. We're hoping to fix this incompatibility soon.
@@ -66,25 +64,30 @@ Then add `@theoplayer/web-ui` to your app:
         configuration='{"libraryLocation":"/path/to/node_modules/theoplayer/","license":"your_theoplayer_license_goes_here"}'
         source='{"sources":{"src":"https://example.com/stream.m3u8"}}'
     ></theoplayer-default-ui>
+    <script>
+        // Optionally, access the underlying THEOplayer player instance
+        const ui = document.querySelector('theoplayer-default-ui');
+        ui.player.addEventListener('playing', () => console.log('THEOplayer is now playing'));
+    </script>
     ```
 -   Option 2: in your JavaScript.
     ```js
     import { DefaultUI } from '@theoplayer/web-ui';
     const ui = new DefaultUI({
-        configuration: {
-            libraryLocation: '/path/to/node_modules/theoplayer/',
-            license: 'your_theoplayer_license_goes_here'
-        }
+        libraryLocation: '/path/to/node_modules/theoplayer/',
+        license: 'your_theoplayer_license_goes_here'
     });
+    // Set a source for the player to play
     ui.source = {
         sources: {
             src: 'https://example.com/stream.m3u8'
         }
     };
+    // Optionally, access the underlying THEOplayer player instance
+    ui.player.addEventListener('playing', () => console.log('THEOplayer is now playing'));
     ```
 
-See [docs/examples/default-ui.html](https://github.com/THEOplayer/web-ui/blob/main/docs/examples/default-ui.html) for a complete
-example.
+See [docs/examples/default-ui.html](https://github.com/THEOplayer/web-ui/blob/main/docs/examples/default-ui.html) for a complete example.
 
 ### Custom UI
 
@@ -107,5 +110,30 @@ If you want to fully customize your video player layout, you can use a `<theopla
 </theoplayer-ui>
 ```
 
-See [docs/examples/custom-ui.html](https://github.com/THEOplayer/web-ui/blob/main/docs/examples/custom-ui.html) for a complete
-example.
+See [docs/examples/custom-ui.html](https://github.com/THEOplayer/web-ui/blob/main/docs/examples/custom-ui.html) for a complete example.
+
+# Legacy browser support
+
+By default, THEOplayer Web UI targets modern browsers that support modern JavaScript syntax (such as [async/await](https://caniuse.com/async-functions)) and native [Custom Elements](https://caniuse.com/custom-elementsv1). This keeps the download size small, so your viewers can spend less time waiting for your page to load and start watching their video faster.
+
+On older browsers (such as Internet Explorer 11 and older smart TVs), you need to load a different version of the THEOplayer Web UI that uses older JavaScript syntax. You also need to load additional polyfills for missing features such as Promises or Custom Elements. We recommend [Polyfill.io](https://polyfill.io/) and [Web Components Polyfills](https://github.com/webcomponents/polyfills) for these.
+
+-   Option 1: in your HTML. This uses [differential serving](https://css-tricks.com/differential-serving/) so modern browsers will load the modern build (with `type="module"`, while legacy browsers will load the legacy build (with `nomodule`).
+
+    ```html
+    <!-- Load polyfills -->
+    <script nomodule src="https://polyfill.io/v3/polyfill.min.js?features=es2015"></script>
+    <script nomodule src="https://unpkg.com/@webcomponents/webcomponentsjs@2.8.0/custom-elements-es5-adapter.js"></script>
+    <script nomodule src="https://unpkg.com/@webcomponents/webcomponentsjs@2.8.0/webcomponents-bundle.js"></script>
+    <!-- Load modern or legacy build -->
+    <script type="module" src="/path/to/node_modules/@theoplayer/web-ui/dist/THEOplayerUI.js"></script>
+    <script nomodule src="/path/to/node_modules/@theoplayer/web-ui/dist/THEOplayerUI.es5.js"></script>
+    ```
+
+-   Option 2: in your JavaScript. This will load the legacy build on both modern and legacy browsers, which is suboptimal. Instead, we recommend configuring your bundler to produce a modern and legacy build of your entire web app, and to import the appropriate version of THEOplayer Web UI for each build flavor.
+
+    ```js
+    import '@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js';
+    import '@webcomponents/webcomponentsjs/webcomponents-bundle.js';
+    import { DefaultUI } from '@theoplayer/web-ui/es5'; // note the "/es5" suffix
+    ```