Skip to content

Commit f742a2d

Browse files
misteroneillmisteroneill
authored
feat: support changes to props (#44)
1 parent 427cb66 commit f742a2d

File tree

8 files changed

+1379
-303
lines changed

8 files changed

+1379
-303
lines changed

Diff for: ‎README.md

+113-100
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
A React component to load a Brightcove Player in the browser.
99

1010
## Brightcove Player Support
11+
1112
This library has [the same support characteristics as the Brightcove Player Loader](https://github.com/brightcove/player-loader#brightcove-player-support).
1213

1314
## Table of Contents
@@ -17,112 +18,136 @@ This library has [the same support characteristics as the Brightcove Player Load
1718

1819

1920
- [Installation](#installation)
20-
- [Usage](#usage)
21-
- [JSX](#jsx)
22-
- [Via `<script>` Tags](#via-script-tags)
23-
- [CommonJS](#commonjs)
24-
- [ES Module](#es-module)
21+
- [Standard Usage with JSX](#standard-usage-with-jsx)
2522
- [Props](#props)
2623
- [`attrs`](#attrs)
2724
- [`baseUrl`](#baseurl)
2825
- [Other Props](#other-props)
26+
- [Effects of Prop Changes](#effects-of-prop-changes)
2927
- [View the Demo](#view-the-demo)
28+
- [Alternate Usage](#alternate-usage)
29+
- [ES Module (without JSX)](#es-module-without-jsx)
30+
- [CommonJS](#commonjs)
31+
- [`<script>` Tag](#script-tag)
3032

3133
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
3234

3335
## Installation
3436

37+
No matter how you use this component, the only place it is available is npm.
38+
3539
```sh
3640
npm install --save @brightcove/react-player-loader
3741
```
3842

39-
## Usage
40-
41-
To include `@brightcove/react-player-loader` on your website or web application, use any of the following methods.
43+
## Standard Usage with JSX
4244

43-
### JSX
45+
Most React applications are using JSX and the toolchain provided by `create-react-app`.
4446

45-
1. Install the module (see [Installation](##Installation))
46-
2. `import` the module in your javascript. IE `import ReactPlayerLoader from '@brightcove/react-player-loader'`
47-
3. Now you can use it however you like, with the `ReactPlayerLoader` variable.
48-
4. See the example below for full usage.
47+
After installing, `import` the module and use the `ReactPlayerLoader` component like any other component in your React application:
4948

50-
> NOTE: React/ReactDOM/global are **NOT** required, they are only used to show a working example.
49+
> **NOTE:** `React`/`ReactDOM` are **NOT** required, they are only used here to show a complete working example!
5150
5251
```js
53-
import document from 'global/document';
5452
import React from 'react';
5553
import ReactDOM from 'react-dom';
5654
import ReactPlayerLoader from '@brightcove/react-player-loader';
5755

5856
let reactPlayerLoader;
5957
const onSuccess = function(success) {
60-
// two ways to get the underlying player/iframe at this point.
61-
console.log(success.ref)
58+
59+
// The player object or iframe element (depending on embed type) can be
60+
// accessed in two ways.
61+
//
62+
// From the success object passed to the `onSuccess` callback:
63+
console.log(success.ref);
64+
65+
// As a property of the component instance:
6266
console.log(reactPlayerLoader.player);
6367
};
6468

6569
reactPlayerLoader = ReactDOM.render(
6670
<ReactPlayerLoader accountId='1234678' onSuccess={onSuccess}/>,
6771
document.getElementById('fixture')
6872
);
69-
7073
```
7174

72-
### Via `<script>` Tags
75+
See [Alternate Usage](#alternate-usage) below for less common ways to use this component.
7376

74-
1. Get the script however you prefer
75-
2. Include the script in your html
76-
3. Use the `BrightcoveReactPlayerLoader` object that this module exports on the `window` object.
77-
4. See the example below for full usage.
77+
## Props
7878

79-
> NOTE: React/ReactDOM are **NOT** required, they are only used to show a working example.
79+
### `attrs`
8080

81-
```html
82-
<div id="fixture"></div>
83-
<script src="//path/to/react.min.js"></script>
84-
<script src="//path/to/react-dom.min.js"></script>
85-
<script src="//path/to/brightcove-react-player-loader.min.js"></script>
86-
<script>
81+
Type: `Object`
8782

88-
var React = window.React;
89-
var ReactDOM = window.ReactDOM;
90-
var ReactPlayerLoader = window.BrightcoveReactPlayerLoader;
83+
Provides attributes (props) to the component element.
9184

92-
var reactPlayerLoader = window.reactPlayerLoader = ReactDOM.render(
93-
React.createElement(ReactPlayerLoader, {
94-
accountId: '1234678',
95-
onSuccess: function(success) {
96-
// two ways to get the underlying player/iframe at this point.
97-
console.log(success.ref)
98-
console.log(reactPlayerLoader.player);
99-
}
100-
}),
101-
document.getElementById('fixture')
102-
);
85+
For example, you may want to customize the `className` of the component (by default, `"brightcove-react-player-loader"`) by setting props on the component like so:
10386

104-
</script>
87+
```jsx
88+
<ReactPlayerLoader attrs={{className: 'my-custom-class'}} />
10589
```
10690

107-
### CommonJS
91+
### `baseUrl`
92+
93+
Type: `string`
94+
95+
Used to override the base URL for the Brightcove Player being embedded.
96+
97+
Most users will never need this prop. By default, players are loaded from Brightcove's player CDN (`players.brightcove.net`).
98+
99+
### Other Props
100+
101+
All props not specified above are passed to the [Brightcove Player Loader](https://github.com/brightcove/player-loader#parameters) with a few differences:
102+
103+
1. We cannot expose the Player Loader promise easily, so you must use the `onSuccess` and `onFailure` callbacks.
104+
2. If you don't provide an `onFailure` callback, the failure will be handled by throwing an error.
105+
3. We need to use `refNode` and `refNodeInsert` internally, so those props will be ignored.
106+
107+
## Effects of Prop Changes
108+
109+
When a prop passed to this component changes, it will have one of two effects:
110+
111+
1. Dispose/reload the player. This is the most common case.
112+
1. Update the player's state (e.g. fetch a new video).
113+
114+
The following props will update the player's state _without_ a reload:
108115

109-
1. Install the module (see [Installation](##Installation))
110-
2. `require` the module in your javascript. IE `var ReactPlayerLoader = require('@brightcove/react-player-loader')`
111-
3. Now you can use it however you like, with the `ReactPlayerLoader` variable.
112-
4. See the example below for full usage.
116+
- `catalogSearch`
117+
- `catalogSequence`
118+
- `playlistId`
119+
- `playlistVideoId`
120+
- `videoId`
113121

114-
> NOTE: React/ReactDOM/global are **NOT** required, they are only used to show a working example.
122+
All other prop changes will cause a complete dispose/reload.
123+
124+
## View the Demo
125+
126+
This repository includes a barebones demo/example page.
127+
128+
1. Clone the repository
129+
2. Move into the repository
130+
3. Run `npm install`
131+
4. Run `npm start`
132+
5. Navigate to `http://localhost:9999` in a browser
133+
134+
## Alternate Usage
135+
136+
### ES Module (without JSX)
137+
138+
After installation, `import` the module in your JavaScript and use the `ReactPlayerLoader` component like any other component in your React application:
139+
140+
> **NOTE:** `React`/`ReactDOM` are **NOT** required, they are only used here to show a complete working example!
115141
116142
```js
117-
var React = require('react');
118-
var ReactDOM = require('react-dom');
119-
var document = require('global/document');
120-
var ReactPlayerLoader = require('@brightcove/react-player-loader');
143+
import React from 'react';
144+
import ReactDOM from 'react-dom';
145+
import ReactPlayerLoader from '@brightcove/react-player-loader';
121146

122-
var reactPlayerLoader = ReactDOM.render(
147+
const reactPlayerLoader = ReactDOM.render(
123148
React.createElement(ReactPlayerLoader, {
124149
accountId: '1234678',
125-
onSuccess: function(success) {
150+
onSuccess(success) {
126151
// two ways to get the underlying player/iframe at this point.
127152
console.log(success.ref)
128153
console.log(reactPlayerLoader.player);
@@ -133,25 +158,21 @@ var reactPlayerLoader = ReactDOM.render(
133158

134159
```
135160

136-
### ES Module
161+
### CommonJS
137162

138-
1. Install the module (see [Installation](##Installation))
139-
2. `import` the module in your javascript. IE `import ReactPlayerLoader from '@brightcove/react-player-loader'`
140-
3. Now you can use it however you like, with the `ReactPlayerLoader` variable.
141-
4. See the example below for full usage.
163+
After installation, `require` the module in your JavaScript and use the `ReactPlayerLoader` component like any other component in your React application:
142164

143-
> NOTE: React/ReactDOM/global are **NOT** required, they are only used to show a working example.
165+
> **NOTE:** `React`/`ReactDOM` are **NOT** required, they are only used here to show a complete working example!
144166
145167
```js
146-
import document from 'global/document';
147-
import React from 'react';
148-
import ReactDOM from 'react-dom';
149-
import ReactPlayerLoader from '@brightcove/react-player-loader';
168+
var React = require('react');
169+
var ReactDOM = require('react-dom');
170+
var ReactPlayerLoader = require('@brightcove/react-player-loader');
150171

151-
const reactPlayerLoader = ReactDOM.render(
172+
var reactPlayerLoader = ReactDOM.render(
152173
React.createElement(ReactPlayerLoader, {
153174
accountId: '1234678',
154-
onSuccess(success) {
175+
onSuccess: function(success) {
155176
// two ways to get the underlying player/iframe at this point.
156177
console.log(success.ref)
157178
console.log(reactPlayerLoader.player);
@@ -162,42 +183,34 @@ const reactPlayerLoader = ReactDOM.render(
162183

163184
```
164185

165-
## Props
186+
### `<script>` Tag
166187

167-
### `attrs`
168-
Type: `Object`
188+
_This case is extremely unlikely to be used._
169189

170-
Provides attributes (props) to the component element.
190+
After installation or loading from a CDN, use a `script` tag to include the module in your HTML and use the global `window.BrightcoveReactPlayerLoader` to construct the component.
171191

172-
For example, you may want to customize the `className` of the component (by default, `"brightcove-react-player-loader"`) by setting props on the component like so:
192+
```html
193+
<div id="fixture"></div>
194+
<script src="//path/to/react.min.js"></script>
195+
<script src="//path/to/react-dom.min.js"></script>
196+
<script src="//path/to/brightcove-react-player-loader.min.js"></script>
197+
<script>
198+
var React = window.React;
199+
var ReactDOM = window.ReactDOM;
173200
174-
```jsx
175-
<ReactPlayerLoader attrs={{className: 'my-custom-class'}} />
201+
var reactPlayerLoader = ReactDOM.render(
202+
React.createElement(window.BrightcoveReactPlayerLoader, {
203+
accountId: '1234678',
204+
onSuccess: function(success) {
205+
// two ways to get the underlying player/iframe at this point.
206+
console.log(success.ref)
207+
console.log(reactPlayerLoader.player);
208+
}
209+
}),
210+
document.getElementById('fixture')
211+
);
212+
</script>
176213
```
177214

178-
### `baseUrl`
179-
Type: `string`
180-
181-
Used to override the base URL for the Brightcove Player being embedded.
182-
183-
Most users will never need this prop. By default, players are loaded from Brightcove's player CDN (`players.brightcove.net`).
184-
185-
### Other Props
186-
All props not specified above are passed to the [Brightcove Player Loader](https://github.com/brightcove/player-loader#parameters) with a few differences:
187-
188-
1. We cannot expose the promise easily, so you will have to use the `onSuccess` and `onFailure` callbacks.
189-
2. If you don't provide an `onFailure` callback, the failure will be handled by throwing an error.
190-
3. We need to use `refNode` and `refNodeInsert` internally, so those options will not be used if passed in.
191-
192-
## View the Demo
193-
This repository includes a barebones demo/example page.
194-
195-
1. Clone the repository
196-
2. Move into the repository
197-
3. Run `npm install`
198-
4. Run `npm start`
199-
5. Navigate to `http://localhost:9999` in a browser
200-
201-
202215
[react]: https://www.npmjs.com/package/react
203216
[react-dom]: https://www.npmjs.com/package/react-dom

Diff for: ‎index.html

+33-13
Original file line numberDiff line numberDiff line change
@@ -4,29 +4,49 @@
44
<meta charset="utf-8">
55
</head>
66
<body>
7+
<p>Nothing will appear below because this page uses an invalid account ID by default.</p>
8+
<p>Open the console and use <code>window.customApp.setState({})</code> to try changing props.</p>
79
<div id="fixture"></div>
810
<script src="node_modules/react/umd/react.development.js"></script>
911
<script src="node_modules/react-dom/umd/react-dom.development.js"></script>
12+
<script src="node_modules/create-react-class/create-react-class.js"></script>
1013
<script src="dist/brightcove-react-player-loader.js"></script>
1114
<script>
1215
(function() {
16+
var fixture = document.getElementById('fixture');
1317
var React = window.React;
1418
var ReactDOM = window.ReactDOM;
15-
var ReactPlayerLoader = window.BrightcoveReactPlayerLoader;
19+
var MyCustomApp = window.createReactClass({
20+
getInitialState: function() {
21+
return {
1622

17-
var reactPlayerLoader = window.reactPlayerLoader = ReactDOM.render(
18-
React.createElement(ReactPlayerLoader, {
19-
accountId: '1',
20-
baseUrl: window.location.origin + '/vendor/',
21-
onSuccess: function(success) {
22-
// two ways to get the underlying player/iframe at this point.
23-
console.log(success.ref)
24-
console.log(reactPlayerLoader.player);
25-
}
26-
}),
27-
document.getElementById('fixture')
28-
);
23+
// Put your account ID, player ID, or other settings here...
24+
accountId: 1,
25+
videoId: 2
26+
};
27+
},
28+
render: function() {
29+
return React.createElement(window.BrightcoveReactPlayerLoader, {
30+
accountId: this.state.accountId,
31+
videoId: this.state.videoId,
32+
onSuccess: function(player) {
33+
if (console) {
34+
console.log('successfully created player', player);
35+
}
36+
},
37+
onFailure: function(err) {
38+
if (console) {
39+
console.log('failed to create player', err);
40+
}
41+
},
42+
key: this.state
43+
});
44+
}
45+
});
46+
47+
window.customApp = ReactDOM.render(React.createElement(MyCustomApp), fixture);
2948
})();
49+
3050
</script>
3151
</body>
3252
</html>

0 commit comments

Comments
 (0)