README.md

@brightcove/react-player-loader

A React component to load a Brightcove Player in the browser.

Brightcove Player Support

This library has the same support characteristics as the Brightcove Player Loader.

Table of Contents

• Installation
• Standard Usage with JSX
• Props
  • attrs
  • baseUrl
  • manualReloadFromPropChanges
  • Other Props
• Effects of Prop Changes
• View the Demo
• Alternate Usage
  • ES Module (without JSX)
  • CommonJS
  • <script> Tag

Installation

No matter how you use this component, the only place it is available is npm.

npm install --save @brightcove/react-player-loader

Standard Usage with JSX

Most React applications are using JSX and the toolchain provided by create-react-app.

After installing, import the module and use the ReactPlayerLoader component like any other component in your React application:

NOTE: React/ReactDOM are NOT required, they are only used here to show a complete working example!

import React from 'react';
import ReactDOM from 'react-dom';
import ReactPlayerLoader from '@brightcove/react-player-loader';

let reactPlayerLoader;
const onSuccess = function(success) {

  // The player object or iframe element (depending on embed type) can be
  // accessed in two ways.
  // 
  // From the success object passed to the `onSuccess` callback:
  console.log(success.ref);

  // As a property of the component instance:
  console.log(reactPlayerLoader.player);
};

reactPlayerLoader = ReactDOM.render(
  <ReactPlayerLoader accountId='1234678' onSuccess={onSuccess}/>,
  document.getElementById('fixture')
);

See Alternate Usage below for less common ways to use this component.

Props

attrs

Type: Object

Provides attributes (props) to the component element.

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:

<ReactPlayerLoader attrs={{className: 'my-custom-class'}} />

baseUrl

Type: string

Used to override the base URL for the Brightcove Player being embedded.

Most users will never need this prop. By default, players are loaded from Brightcove's player CDN (players.brightcove.net).

manualReloadFromPropChanges

Type: boolean

Used to specify if reloading the player after prop changes will be handled manually. This can be done by calling refToReactPlayerLoader.loadPlayer().

See Effects of Prop Changes below for the effects of prop changes.

Other Props

All props not specified above are passed to the Brightcove Player Loader with a few differences:

1. We cannot expose the Player Loader promise easily, so you must use the onSuccess and onFailure callbacks.
2. If you don't provide an onFailure callback, the failure will be handled by throwing an error.
3. We need to use refNode and refNodeInsert internally, so those props will be ignored.

Effects of Prop Changes

When a prop passed to this component changes, it will have one of two effects:

1. Dispose/reload the player. This is the most common case.
2. Update the player's state (e.g. fetch a new video).

The following props will update the player's state without a reload:

• catalogSearch
• catalogSequence
• playlistId
• playlistVideoId
• videoId

All other prop changes, excluding props that are function's, will cause a complete dispose/reload.

View the Demo

This repository includes a barebones demo/example page.

1. Clone the repository
2. Move into the repository
3. Run npm install
4. Run npm start
5. Navigate to http://localhost:9999 in a browser

Alternate Usage

ES Module (without JSX)

After installation, import the module in your JavaScript and use the ReactPlayerLoader component like any other component in your React application:

NOTE: React/ReactDOM are NOT required, they are only used here to show a complete working example!

import React from 'react';
import ReactDOM from 'react-dom';
import ReactPlayerLoader  from '@brightcove/react-player-loader';

const reactPlayerLoader = ReactDOM.render(
  React.createElement(ReactPlayerLoader, {
    accountId: '1234678',
    onSuccess(success) {
      // two ways to get the underlying player/iframe at this point.
      console.log(success.ref)
      console.log(reactPlayerLoader.player);
    }
  }),
  document.getElementById('fixture')
);

CommonJS

After installation, require the module in your JavaScript and use the ReactPlayerLoader component like any other component in your React application:

NOTE: React/ReactDOM are NOT required, they are only used here to show a complete working example!

var React = require('react');
var ReactDOM = require('react-dom');
var ReactPlayerLoader = require('@brightcove/react-player-loader');

var reactPlayerLoader = ReactDOM.render(
  React.createElement(ReactPlayerLoader, {
    accountId: '1234678',
    onSuccess: function(success) {
      // two ways to get the underlying player/iframe at this point.
      console.log(success.ref)
      console.log(reactPlayerLoader.player);
    }
  }),
  document.getElementById('fixture')
);

<script> Tag

This case is extremely unlikely to be used.

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.

<div id="fixture"></div>
<script src="//path/to/react.min.js"></script>
<script src="//path/to/react-dom.min.js"></script>
<script src="//path/to/brightcove-react-player-loader.min.js"></script>
<script>
  var React = window.React;
  var ReactDOM = window.ReactDOM;

  var reactPlayerLoader = ReactDOM.render(
    React.createElement(window.BrightcoveReactPlayerLoader, {
      accountId: '1234678',
      onSuccess: function(success) {
        // two ways to get the underlying player/iframe at this point.
        console.log(success.ref)
        console.log(reactPlayerLoader.player);
      }
    }),
    document.getElementById('fixture')
  );
</script>