Merge pull request #56 from THEOplayer/update-docs

Add getting started guide and migrate React examples for new documentation website
THEOplayer · Mar 19, 2024 · 4660a0a · 4660a0a
2 parents c19b648 + 6ac92d9
commit 4660a0a
Show file tree

Hide file tree

Showing 22 changed files with 901 additions and 22 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,8 @@
+---
+description: Find out what's new in Open Video UI for Web.
+sidebar_custom_props: { 'icon': '📰' }
+---
+
 # Changelog
 
 > **Tags:**

diff --git a/README.md b/README.md
@@ -127,7 +127,7 @@ If you want to fully customize your video player layout, you can use a `<theopla
 
 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
+### Legacy browser support
 
 By default, Open Video UI for Web 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.
 

diff --git a/docs/components/Example.tsx b/docs/components/Example.tsx
@@ -2,6 +2,7 @@ import React, {
     type ComponentPropsWithoutRef,
     forwardRef,
     type JSX,
+    type ReactNode,
     useCallback,
     useEffect,
     useImperativeHandle,
@@ -12,9 +13,10 @@ import React, {
 
 export interface Props extends ComponentPropsWithoutRef<'iframe'> {
     hideDeviceType?: boolean;
+    options?: ReactNode;
 }
 
-export default forwardRef<HTMLIFrameElement | null, Props>(function Example({ hideDeviceType, ...props }: Props, ref): JSX.Element {
+export default forwardRef<HTMLIFrameElement | null, Props>(function Example({ hideDeviceType, options, ...props }: Props, ref): JSX.Element {
     const iframeRef = useRef<HTMLIFrameElement | null>(null);
     useImperativeHandle(ref, () => iframeRef.current, [iframeRef.current]);
 
@@ -29,17 +31,22 @@ export default forwardRef<HTMLIFrameElement | null, Props>(function Example({ hi
     return (
         <>
             <iframe ref={iframeRef} {...props}></iframe>
-            {!hideDeviceType && (
+            {(options || !hideDeviceType) && (
                 <p>
-                    <label style={{ userSelect: 'none' }}>
-                        Override device type{' '}
-                        <select value={deviceType} onChange={(e) => setDeviceType(e.target.value)}>
-                            <option value=""></option>
-                            <option value="desktop">Desktop</option>
-                            <option value="mobile">Mobile</option>
-                            <option value="tv">TV</option>
-                        </select>
-                    </label>
+                    {!hideDeviceType && (
+                        <div>
+                            <label style={{ userSelect: 'none' }}>
+                                Override device type:{' '}
+                                <select value={deviceType} onChange={(e) => setDeviceType(e.target.value)}>
+                                    <option value=""></option>
+                                    <option value="desktop">Desktop</option>
+                                    <option value="mobile">Mobile</option>
+                                    <option value="tv">TV</option>
+                                </select>
+                            </label>
+                        </div>
+                    )}
+                    {options}
                 </p>
             )}
         </>

diff --git a/docs/examples/_category_.json b/docs/examples/_category_.json
diff --git a/docs/examples/ads.mdx b/docs/examples/ads.mdx
@@ -1,5 +1,6 @@
 ---
 sidebar_position: 11
+sidebar_custom_props: { 'icon': '💰' }
 ---
 
 # Advertisements

diff --git a/docs/examples/custom-ui.mdx b/docs/examples/custom-ui.mdx
@@ -1,5 +1,6 @@
 ---
 sidebar_position: 20
+sidebar_custom_props: { 'icon': '▶️' }
 ---
 
 # Custom UI

diff --git a/docs/examples/default-ui.mdx b/docs/examples/default-ui.mdx
@@ -1,5 +1,6 @@
 ---
 sidebar_position: 10
+sidebar_custom_props: { 'icon': '▶️' }
 ---
 
 # Default UI

diff --git a/docs/examples/nitflex.mdx b/docs/examples/nitflex.mdx
@@ -1,5 +1,6 @@
 ---
 sidebar_position: 22
+sidebar_custom_props: { 'icon': '📺' }
 ---
 
 # Custom UI: Nitflex theme

diff --git a/docs/examples/portrait.mdx b/docs/examples/portrait.mdx
@@ -1,5 +1,6 @@
 ---
 sidebar_position: 21
+sidebar_custom_props: { 'icon': '📱' }
 ---
 
 # Custom UI: Portrait theme

diff --git a/docs/examples/styling.mdx b/docs/examples/styling.mdx
@@ -1,5 +1,6 @@
 ---
 sidebar_position: 12
+sidebar_custom_props: { 'icon': '🎨' }
 ---
 
 # Styling the default UI

diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx
@@ -0,0 +1,143 @@
+---
+description: Start building your UI in just a few minutes!
+sidebar_position: 1
+sidebar_custom_props: { 'icon': '🚀' }
+---
+
+# Getting started
+
+## Installation
+
+1. This project requires the THEOplayer Web SDK to be installed.
+    ```sh
+    npm install theoplayer
+    ```
+    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 Open Video UI for Web.
+    ```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/THEOplayer.chromeless.js"></script>
+        <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';
+        ```
+        Open Video UI will import THEOplayer from `theoplayer/chromeless`.
+        If you're using a bundler such as Webpack or Rollup, this dependency should automatically get bundled with your web app.
+        Alternatively, you can use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to let the browser resolve it:
+        ```html
+        <script type="importmap">
+            {
+                "imports": {
+                    "theoplayer/chromeless": "/path/to/node_modules/theoplayer/THEOplayer.chromeless.esm.js"
+                }
+            }
+        </script>
+        <!-- Import maps polyfill for browsers without import maps support (e.g. Safari 16.3) -->
+        <script async src="https://ga.jspm.io/npm:[email protected]/dist/es-module-shims.js" crossorigin="anonymous"></script>
+        <script type="module" src="/path/to/my_app.js"></script>
+        ```
+
+## Usage
+
+### Default UI
+
+`<theoplayer-default-ui>` provides a fully-featured video player experience with minimal setup, and allows for small customizations such as changing colors or fonts.
+
+-   Option 1: in your HTML.
+    ```html
+    <theoplayer-default-ui
+        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({
+        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 [this page](examples/default-ui.mdx) for a complete example.
+
+### Custom UI
+
+If you want to fully customize your video player layout, you can use a `<theoplayer-ui>` instead.
+
+```html
+<theoplayer-ui
+    configuration='{"libraryLocation":"/path/to/node_modules/theoplayer/","license":"your_theoplayer_license_goes_here"}'
+    source='{"sources":{"src":"https://example.com/stream.m3u8"}}'
+>
+    <!-- Choose your own layout using the provided components (or your own!) -->
+    <theoplayer-control-bar>
+        <theoplayer-time-range></theoplayer-time-range>
+    </theoplayer-control-bar>
+    <theoplayer-control-bar>
+        <theoplayer-play-button></theoplayer-play-button>
+        <theoplayer-mute-button></theoplayer-mute-button>
+        <theoplayer-volume-range></theoplayer-volume-range>
+    </theoplayer-control-bar>
+</theoplayer-ui>
+```
+
+See [this page](examples/custom-ui.mdx) for a complete example.
+
+### Legacy browser support
+
+By default, Open Video UI for Web 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 Open Video 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
+    <!-- Modern browsers -->
+    <script type="importmap">
+        {
+            "imports": {
+                "theoplayer/chromeless": "/path/to/node_modules/theoplayer/THEOplayer.chromeless.esm.js"
+            }
+        }
+    </script>
+    <!-- Import maps polyfill for browsers without import maps support (e.g. Safari 16.3) -->
+    <script async src="https://ga.jspm.io/npm:[email protected]/dist/es-module-shims.js" crossorigin="anonymous"></script>
+    <script type="module" src="/path/to/node_modules/@theoplayer/web-ui/dist/THEOplayerUI.mjs"></script>
+    <!-- Legacy browsers -->
+    <script nomodule src="https://polyfill.io/v3/polyfill.min.js?features=es2015"></script>
+    <script nomodule src="https://unpkg.com/@webcomponents/[email protected]/custom-elements-es5-adapter.js"></script>
+    <script nomodule src="https://unpkg.com/@webcomponents/[email protected]/webcomponents-bundle.js"></script>
+    <script nomodule src="/path/to/node_modules/theoplayer/THEOplayer.chromeless.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 Open Video 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
+    ```
diff --git a/docs/react/components/ReactExample.tsx b/docs/react/components/ReactExample.tsx
@@ -0,0 +1,57 @@
+import React, { type JSX, useEffect, useState } from 'react';
+import Example, { type Props as ExampleProps } from '../../components/Example';
+
+const sources = {
+    hls: {
+        sources: { src: 'https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8' },
+        metadata: { title: "Elephant's Dream" },
+        textTracks: [
+            {
+                default: true,
+                src: 'https://cdn.theoplayer.com/video/elephants-dream/thumbnails.vtt',
+                label: 'thumbnails',
+                kind: 'metadata'
+            }
+        ]
+    },
+    dash: {
+        sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8' },
+        metadata: { title: 'Big Buck Bunny' }
+    }
+};
+
+export interface Props extends ExampleProps {}
+
+export default function ReactExample(props: Props): JSX.Element {
+    const [iframe, setIframe] = useState<HTMLIFrameElement | null>(null);
+    const [sourceName, setSourceName] = useState('hls');
+
+    // Send message to <iframe> when source changes
+    useEffect(() => {
+        iframe?.contentWindow.postMessage({
+            type: 'source',
+            source: sources[sourceName]
+        });
+    }, [iframe, sourceName]);
+
+    return (
+        <Example
+            ref={setIframe}
+            {...props}
+            options={
+                <div>
+                    <label>
+                        Source:{' '}
+                        <select value={sourceName} onChange={(ev) => setSourceName(ev.target.value)}>
+                            {Object.entries(sources).map(([key, value]) => (
+                                <option key={key} value={key}>
+                                    {value.metadata.title}
+                                </option>
+                            ))}
+                        </select>
+                    </label>
+                </div>
+            }
+        />
+    );
+}