Merge pull request #17 from aiham/dev

Release 0.5.0

Author: aiham

CONTRIBUTING.md

@@ -22,7 +22,8 @@ For a contribution to be accepted:
 
 * The test suite must be complete and pass
 * Code must follow existing styling conventions
-* Commit messages must be descriptive. Related issues should be mentioned by number.
+* Commit messages must be descriptive. Related issues should be mentioned by number
+* If the contribution includes a change to the dependency list then the `yarn.lock` file must be updated
 
 If the contribution doesn't meet these criteria, a maintainer will discuss it with you on the Issue. You can still continue to add more commits to the branch you have sent the Pull Request from.
 

README.md

@@ -61,7 +61,7 @@ There is an example application provided in `example/` and you can run it with t
 1. Edit `config.js`:
   1. Add your OpenTok API key, Session ID and Token (https://tokbox.com/account/)
   1. Add your Chrome Extension ID (https://tokbox.com/developer/guides/screen-sharing/js/)
-1. `npm install`
+1. `yarn` (or `npm install`)
 1. `npm run example`
 1. Visit `http://localhost:8000` in your browser
 
@@ -162,31 +162,44 @@ The `opentok-react` library comprises of:
 | apiKey | String | Yes | TokBox API Key
 | sessionId | String | Yes | TokBox Session ID
 | token | String | Yes | TokBox token
-| eventHandlers | Object<Function> | No | Event handlers passed into `session.on`
-| onConnect | Function() | No | Invoked when `session.connect` successfully completes
-| onError | Function(err) | No | Invoked when `session.connect` fails
+| eventHandlers | Object<Function> | No | Event handlers passed into [session.on](https://tokbox.com/developer/sdks/js/reference/Session.html#on)
+| onConnect | Function() | No | Invoked when [session.connect](https://tokbox.com/developer/sdks/js/reference/Session.html#connect) successfully completes
+| onError | Function(err) | No | Invoked when [session.connect](https://tokbox.com/developer/sdks/js/reference/Session.html#connect) fails
+
+The `OTSession` component manages the connection to an OpenTok [Session](https://tokbox.com/developer/sdks/js/reference/Session.html). It passes the Session instance as the `session` prop to its child components. It is recommended that you nest `OTPublisher` and `OTStreams` inside `OTSession`:
+
+```html
+<OTSession apiKey="your-api-key" sessionId="your-session-id" token="your-session-token">
+  <OTPublisher />
+  <OTStreams>
+    <OTSubscriber />
+  </OTStreams>
+</OTSession>
+```
 
 ### OTPublisher Component
 
 | Prop | Type | Required | Description |
 | --- | --- | --- | --- |
-| session | [Session](https://tokbox.com/developer/sdks/js/reference/Session.html) | No | OpenTok Session instance
-| properties | Object | No | Properties passed into `OT.initPublisher`
-| eventHandlers | Object&lt;Function&gt; | No | Event handlers passed into `publisher.on`
-| onInit | Function() | No | Invoked when `OT.initPublisher` successfully completes
-| onPublish | Function() | No | Invoked when `session.publish` successfully completes
-| onError | Function(err) | No | Invoked when either `OT.initPublisher` or `session.publish` fail
+| session | [Session](https://tokbox.com/developer/sdks/js/reference/Session.html) | No | OpenTok Session instance. This is auto populated by wrapping `OTPublisher` with `OTSession`
+| properties | Object | No | Properties passed into [OT.initPublisher](https://tokbox.com/developer/sdks/js/reference/OT.html#initPublisher)
+| eventHandlers | Object&lt;Function&gt; | No | Event handlers passed into [publisher.on](https://tokbox.com/developer/sdks/js/reference/Publisher.html#on)
+| onInit | Function() | No | Invoked when [OT.initPublisher](https://tokbox.com/developer/sdks/js/reference/OT.html#initPublisher) successfully completes
+| onPublish | Function() | No | Invoked when [session.publish](https://tokbox.com/developer/sdks/js/reference/Session.html#publish) successfully completes
+| onError | Function(err) | No | Invoked when either [OT.initPublisher](https://tokbox.com/developer/sdks/js/reference/OT.html#initPublisher) or [session.publish](https://tokbox.com/developer/sdks/js/reference/Session.html#publish) fail
 
-The `OTPublisher` component will initialise a publisher and publish to a specified session upon mounting. You must specify a [Session](https://tokbox.com/developer/sdks/js/reference/Session.html) object using the `session` prop.
+The `OTPublisher` component will initialise a publisher and publish to a specified session upon mounting. It will also ensure the Publisher video element is attached to the DOM inside the component rather than appending to the body (which is the Publisher's default behaviour).
 
-```js
-class MyApp extends React.Component {
-  render() {
-    return (
-      <OTPublisher session={this.sessionHelper.session} />
-    );
-  }
-}
+```html
+<OTSession apiKey="your-api-key" sessionId="your-session-id" token="your-session-token">
+  <OTPublisher />
+</OTSession>
+```
+
+If you are not using `OTSession` then you must specify a [Session](https://tokbox.com/developer/sdks/js/reference/Session.html) object using the `session` prop.
+
+```html
+<OTPublisher session={this.sessionHelper.session} />
 ```
 
 Use the `properties` prop to specify a properties object for [OT.initPublisher](https://tokbox.com/developer/sdks/js/reference/OT.html#initPublisher) and the `eventHandlers` prop to specify an object of event handlers for [Publisher#on](https://tokbox.com/developer/sdks/js/reference/Publisher.html#on).
@@ -213,26 +226,34 @@ class MyApp extends React.Component {
 
   render() {
     return (
-      <OTPublisher
-        session={this.sessionHelper.session}
-        properties={this.publisherProperties}
-        eventHandlers={this.publisherEventHandlers}
-      />
+      <OTSession apiKey="your-api-key" sessionId="your-session-id" token="your-session-token">
+        <OTPublisher
+          properties={this.publisherProperties}
+          eventHandlers={this.publisherEventHandlers}
+        />
+      </OTSession>
     );
   }
 }
 ```
 
-#### TODO
-- Describe `getPublisher()` method.
-- Explain which properties `OTPublisher` will monitor for changes.
-- Explain that this component will not cause publisher to be appended to body.
+The `properties` prop is used for initial set up of the Publisher and making changes to it will not update the Publisher, you will instead need to invoke Publisher methods. To facilitate this the Publisher instance is exposed via the `getPublisher()` component method. You should always call this method to get the latest Publisher instance instead of keeping a reference to it as it's possible for the Publisher instance to change, leaving you with a stale reference.
+
+However, for convenience the `OTPublisher` does watch for changes on a few keys of the `properties` object and makes the necessary changes. Currently these are:
+
+| Publisher Property | Action |
+| --- | --- |
+| videoSource | Destroys and recreates the Publisher with the new video source. This is the only way to change the video source of a Publisher. This is used in the example application to allow the user to toggle between publishing their camera and publishing their screen |
+| publishAudio | Calls [publisher.publishAudio()](https://tokbox.com/developer/sdks/js/reference/Publisher.html#publishAudio) to toggle audio on and off |
+| publishVideo | Calls [publisher.publishVideo()](https://tokbox.com/developer/sdks/js/reference/Publisher.html#publishVideo) to toggle video on and off |
+
+There are plans to support more Publisher properties but for now you will have to call `getPublisher()` to retrieve the Publisher instance and make the necessary changes yourself.
 
 ### OTStreams Component
 
 | Prop | Type | Required | Description |
 | --- | --- | --- | --- |
-| children | OTSubscriber | Yes | Must only have a single `OTSubscriber` component (or similar component that accepts `session` and `stream` props)
+| children | ReactElement | Yes | Must have a single child component that accepts `session` and `stream` props, eg. `OTSubscriber`
 | session | [Session](https://tokbox.com/developer/sdks/js/reference/Session.html) | Yes | OpenTok Session instance. This is auto populated by wrapping `OTStreams` with `OTSession`
 | streams | Array&lt;[Stream](https://tokbox.com/developer/sdks/js/reference/Stream.html)&gt; | No | Array of OpenTok Stream instances. This is auto populated by wrapping `OTStreams` with `OTSession`
 
@@ -247,34 +268,73 @@ class MyApp extends React.Component {
 | onSubscribe | Function() | No | Invoked when `session.subscribe` successfully completes
 | onError | Function(err) | No | Invoked when `session.subscribe` fails
 
-The `OTSubscriber` component will subscribe to a specified stream from a specified session upon mounting. You must provide a [Stream](https://tokbox.com/developer/sdks/js/reference/Stream.html) object using the `stream` prop and a [Session](https://tokbox.com/developer/sdks/js/reference/Session.html) object using the `session` prop.
+The `OTSubscriber` component will subscribe to a specified stream from a specified session upon mounting. It will also ensure the Subscriber video element is attached to the DOM inside the component rather than appending to the body (which is the Subscriber's default behaviour).
+
+```html
+<OTStreams>
+  <OTSubscriber />
+</OTStreams>
+```
+
+If you are not using `OTStreams` then you must provide a [Stream](https://tokbox.com/developer/sdks/js/reference/Stream.html) object using the `stream` prop and a [Session](https://tokbox.com/developer/sdks/js/reference/Session.html) object using the `session` prop.
+
+```js
+{this.sessionHelper.streams.map(stream => (
+  <OTSubscriber
+    key={stream.id}
+    session={this.sessionHelper.session}
+    stream={stream}
+  />
+))}
+```
+
+Use the `properties` prop to specify a properties object for [session.subscribe](https://tokbox.com/developer/sdks/js/reference/Session.html#subscribe) and the `eventHandlers` prop to specify an object of event handlers for [Subscriber#on](https://tokbox.com/developer/sdks/js/reference/Subscriber.html#on).
 
 ```js
 class MyApp extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.subscriberProperties = {
+      preferredFrameRate: 15,
+      showControls: false
+    };
+
+    this.subscriberEventHandlers = {
+      videoDisabled: event => {
+        console.log('Subscriber video disabled!');
+      },
+      videoEnabled: event => {
+        console.log('Subscriber video enabled!');
+      }
+    };
+  }
+
   render() {
     return (
-      <div>
-        {this.sessionHelper.streams.map(stream => {
-          return (
-            <OTSubscriber
-              key={stream.id}
-              session={this.sessionHelper.session}
-              stream={stream}
-            />
-          );
-        })}
-      </div>
+      <OTSession apiKey="your-api-key" sessionId="your-session-id" token="your-session-token">
+        <OTStreams>
+          <OTSubscriber
+            properties={this.subscriberProperties}
+            eventHandlers={this.subscriberEventHandlers}
+          />
+        </OTStreams>
+      </OTSession>
     );
   }
 }
 ```
 
-#### TODO
-- Describe `getSubscriber()` method.
-- Describe `properties` prop.
-- Describe `eventHandlers` prop.
-- Explain which properties `OTPublisher` will monitor for changes.
-- Explain that this component will not cause subscriber to be appended to body.
+The `properties` prop is used for initial set up of the Subscriber and making changes to it will not update the Subscriber, you will instead need to invoke Subscriber methods. To facilitate this the Subscriber instance is exposed via the `getSubscriber()` component method. You should always call this method to get the latest Subscriber instance instead of keeping a reference to it as it's possible for the Subscriber instance to change, leaving you with a stale reference.
+
+However, for convenience the `OTSubscriber` does watch for changes on a few keys of the `properties` object and makes the necessary changes. Currently these are:
+
+| Subscriber Property | Action |
+| --- | --- |
+| subscribeToAudio | Calls [subscriber.subscribeToAudio()](https://tokbox.com/developer/sdks/js/reference/Subscriber.html#subscribeToAudio) to toggle audio on and off |
+| subscribeToVideo | Calls [subscriber.subscribeToVideo()](https://tokbox.com/developer/sdks/js/reference/Subscriber.html#subscribeToVideo) to toggle video on and off |
+
+There are plans to support more Subscriber properties but for now you will have to call `getSubscriber()` to retrieve the Subscriber instance and make the necessary changes yourself.
 
 ### createSession Helper
 
@@ -313,13 +373,13 @@ Use of this helper is optional and you can instead use the `OTSession` component
 | Prop | Type | Required | Description |
 | --- | --- | --- | --- |
 | opentokClientUrl | String | No | The URL of the OpenTok client script to load. It defaults to `https://static.opentok.com/v2/js/opentok.min.js`.
-| loadingDelegate | Element | No | An element that will be displayed while the OpenTok client script is loading. It defaults to an empty `<div />`.
+| loadingDelegate | ReactElement | No | An element that will be displayed while the OpenTok client script is loading. It defaults to an empty `<div />`.
 
 In larger applications, one might not want to load the `opentok.js` client with a `<script>` tag all the time. The `preloadScript` higher-order component will do this for you at the appropriate time.
 
 For example, imagine you have a React Router application with the following route structure:
 
-```javascript
+```html
 <Router>
   <Route path="/">
     <IndexRoute component="..." />
@@ -344,7 +404,7 @@ export default preloadScript(App);
 
 1. `git clone https://github.com/aiham/opentok-react.git`
 1. `cd opentok-react/`
-1. `npm install`
+1. `yarn` (or `npm install`)
 1. Modify code in `src/`
 1. `npm run build`
 1. Check that files in `dist/` have been updated.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentok-react",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "React components for OpenTok.js",
   "main": "dist/index.js",
   "scripts": {
@@ -27,7 +27,8 @@
   "license": "MIT",
   "dependencies": {
     "lodash": "^4.13.1",
-    "react": "^15.1.0",
+    "prop-types": "^15.5.10",
+    "react": "^15.5.0",
     "react-display-name": "^0.2.0",
     "scriptjs": "^2.5.8",
     "uuid": "^3.0.1"
@@ -56,8 +57,9 @@
     "karma-jasmine": "^1.1.0",
     "karma-spec-reporter": "^0.0.26",
     "opentok-test-scripts": "^3.2.1",
-    "react-addons-test-utils": "^15.4.1",
-    "react-dom": "^15.1.0",
+    "react-addons-test-utils": "^15.5.1",
+    "react-dom": "^15.5.0",
+    "react-test-renderer": "^15.5.4",
     "travis-multirunner": "^3.1.0",
     "watchify": "^3.8.0"
   },

src/OTPublisher.js

@@ -1,4 +1,5 @@
-import React, { Component, PropTypes } from 'react';
+import React, { Component } from 'react';
+import PropTypes from 'prop-types';
 import once from 'lodash/once';
 import uuid from 'uuid';
 

src/OTSession.js

@@ -1,4 +1,5 @@
-import React, { Component, PropTypes, Children, cloneElement } from 'react';
+import React, { Component, Children, cloneElement } from 'react';
+import PropTypes from 'prop-types';
 
 import createSession from './createSession';
 
@@ -59,7 +60,7 @@ export default class OTSession extends Component {
 }
 
 OTSession.propTypes = {
-  children: React.PropTypes.oneOfType([
+  children: PropTypes.oneOfType([
     PropTypes.element,
     PropTypes.arrayOf(PropTypes.element),
   ]).isRequired,

src/OTStreams.js

@@ -1,4 +1,5 @@
-import React, { PropTypes, Children, cloneElement } from 'react';
+import React, { Children, cloneElement } from 'react';
+import PropTypes from 'prop-types';
 
 export default function OTStreams(props) {
   if (!props.session) {
@@ -27,7 +28,7 @@ OTStreams.propTypes = {
     publish: PropTypes.func,
     subscribe: PropTypes.func,
   }),
-  streams: PropTypes.arrayOf(React.PropTypes.object),
+  streams: PropTypes.arrayOf(PropTypes.object),
 };
 
 OTStreams.defaultProps = {

src/OTSubscriber.js

@@ -1,4 +1,5 @@
-import React, { Component, PropTypes } from 'react';
+import React, { Component } from 'react';
+import PropTypes from 'prop-types';
 import uuid from 'uuid';
 
 export default class OTSubscriber extends Component {

src/preloadScript.js

@@ -1,4 +1,5 @@
-import React, { Component, PropTypes } from 'react';
+import React, { Component } from 'react';
+import PropTypes from 'prop-types';
 import getDisplayName from 'react-display-name';
 import scriptjs from 'scriptjs';