Merge pull request #5 from aiham/dev

Release 0.4.0

.npmignore

@@ -1,2 +1,6 @@
-src/
 example/
+src/
+test/
+karma.conf.js
+.travis.yml
+.npmignore

.travis.yml

@@ -0,0 +1,29 @@
+sudo: required
+language: node_js
+node_js:
+  - 6
+
+before_install:
+  - export DISPLAY=:99.0
+  - sh -e /etc/init.d/xvfb start
+
+script: ./node_modules/.bin/run-tests
+
+after_failure:
+  - for file in *.log; do echo $file; echo "======================"; cat $file; done || true
+
+env:
+  matrix:
+    - BROWSER=chrome  BVER=stable
+    - BROWSER=firefox BVER=stable
+    - UNIT_CMD='npm run lint'
+  global:
+    - TRAVIS=true
+    - UNIT_CMD='npm run unit'
+
+matrix:
+  fast_finish: true
+
+notifications:
+  email:
+    - aiham@aiham.net

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing Guidelines
+
+For anyone looking to get involved to this project, we are glad to hear from you. Here are a few types of contributions that we would be interested in hearing about.
+
+* Bug fixes
+  - If you find a bug, please first report it using Github Issues.
+  - Issues that have already been identified as a bug will be labelled `bug`.
+  - If you'd like to submit a fix for a bug, send a Pull Request from your own fork and mention the Issue number.
+    + Include a test that isolates the bug and verifies that it was fixed.
+* New Features
+  - If you'd like to accomplish something in the library that it doesn't already do, describe the problem in a new Github Issue.
+  - Issues that have been identified as a feature request will be labelled `enhancement`.
+  - If you'd like to implement the new feature, please wait for feedback from the project maintainers before spending too much time writing the code. In some cases, `enhancement`s may not align well with the project objectives at the time.
+* Tests, Documentation, Miscellaneous
+  - If you think the test coverage could be improved, the documentation could be clearer, you've got an alternative implementation of something that may have more advantages, or any other change we would still be glad hear about it.
+  - If its a trivial change, go ahead and send a Pull Request with the changes you have in mind
+  - If not, open a Github Issue to discuss the idea first.
+
+## Requirements
+
+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.
+
+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.
+
+## How To
+
+1. Fork this repository on GitHub.
+1. Clone/fetch your fork to your local development machine.
+1. Create a new branch (e.g. `issue-12`, `feat/add_foo`, etc) and check it out.
+1. Make your changes and commit them. (Did the tests pass?)
+1. Push your new branch to your fork. (e.g. `git push myname issue-12`)
+1. Open a Pull Request from your new branch to the original fork's `dev` branch.
+1. Ensure the Pull Request's automated status checks have all passed and are ready for review.
+
+## Code structure
+
+Source code is to be placed in the [src](src/) directory and tests in the [test](test/) directory. Test files should be suffixed with `.spec.js` and follow a similar test suite structure to existing test files.
+
+All source and test code should follow the same style as existing source and test code and will be enforced by an automated [eslint](http://eslint.org/) style check that runs on every Pull Request.

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016-2017 Aiham Hammami
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,6 +1,6 @@
 # opentok-react
 
-[![npm version](https://badge.fury.io/js/opentok-react.svg)](https://badge.fury.io/js/opentok-react)
+[![npm version](https://badge.fury.io/js/opentok-react.svg)](https://badge.fury.io/js/opentok-react) [![Build Status](https://travis-ci.org/aiham/opentok-react.svg?branch=master)](https://travis-ci.org/aiham/opentok-react)
 
 React components for OpenTok.js
 
@@ -19,7 +19,9 @@ React components for OpenTok.js
   - [OTStreams Component](#otstreams-component)
   - [OTSubscriber Component](#otsubscriber-component)
   - [createSession Helper](#createsession-helper)
+  - [preloadScript Higher-Order Component](#preloadscript-higher-order-component)
 - [Custom Build](#custom-build)
+- [Contributing](#contributing)
 - [Tests](#tests)
 
 ## Pre-Requisites
@@ -31,16 +33,24 @@ React components for OpenTok.js
 
 Add `opentok-react` as a dependency of your application:
 
+```sh
+yarn add opentok-react
+```
+
+Or if you're still using npm:
+
 ```sh
 npm install --save opentok-react
 ```
 
-Include `opentok.js` before your application:
+Then include `opentok.js` before your application:
 
 ```html
 <script src="https://static.opentok.com/v2/js/opentok.min.js"></script>
 ```
 
+Alternatively, wrap your top-level component using OpenTok with the [`preloadScript`](#preloadscript-higher-order-component) HOC. The HOC will take care of loading `opentok.js` for you before rendering.
+
 ## Example App
 
 There is an example application provided in `example/` and you can run it with the following steps:
@@ -66,19 +76,13 @@ The following sections explains how to import and use `opentok-react` in your Re
 Import the `opentok-react` components into your React application:
 
 ```js
-import { OTSession, OTPublisher, OTStreams, OTSubscriber, createSession } from 'opentok-react';
+import { OTSession, OTPublisher, OTStreams, OTSubscriber } from 'opentok-react';
 ```
 
 Or `require` it if you need to use CommonJS modules:
 
 ```js
-var otReact = require('opentok-react');
-
-var OTSession = otReact.OTSession;
-var OTPublisher = otReact.OTPublisher;
-var OTStreams = otReact.OTStreams;
-var OTSubscriber = otReact.OTSubscriber;
-var createSession = otReact.createSession;
+const { OTSession, OTPublisher, OTStreams, OTSubscriber } = require('opentok-react');
 ```
 
 ### Example with OTSession Component
@@ -142,20 +146,37 @@ class MyApp extends React.Component {
 
 ## API Reference
 
-The `opentok-react` library is comprised of:
+The `opentok-react` library comprises of:
 
 - `OTSession` Component
 - `OTPublisher` Component
 - `OTStreams` Component
 - `OTSubscriber` Component
 - `createSession` Helper
+- `preloadScript` Higher-Order Component
 
 ### OTSession Component
 
-TODO
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| apiKey | String | Yes | TokBox API Key
+| sessionId | String | Yes | TokBox Session ID
+| token | String | Yes | TokBox token
+| eventHandlers | Object&lt;Function&gt; | 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
 
 ### 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
+
 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.
 
 ```js
@@ -209,10 +230,23 @@ class MyApp extends React.Component {
 
 ### OTStreams Component
 
-TODO
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| children | OTSubscriber | Yes | Must only have a single `OTSubscriber` component (or similar component that accepts `session` and `stream` props)
+| 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`
 
 ### OTSubscriber Component
 
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| session | [Session](https://tokbox.com/developer/sdks/js/reference/Session.html) | No | OpenTok Session instance. This is auto populated by wrapping `OTSubscriber` with `OTStreams`
+| stream | [Stream](https://tokbox.com/developer/sdks/js/reference/Stream.html) | No | OpenTok Stream instance. This is auto populated by wrapping `OTSubscriber` with `OTStreams`
+| properties | Object | No | Properties passed into `session.subscribe`
+| eventHandlers | Object&lt;Function&gt; | No | Event handlers passed into `subscriber.on`
+| 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.
 
 ```js
@@ -273,6 +307,39 @@ The `createSession` helper returns an object with the following properties:
 
 Use of this helper is optional and you can instead use the `OTSession` component or directly call [OT.initSession](https://tokbox.com/developer/sdks/js/reference/OT.html#initSession) and listen to [streamCreated](https://tokbox.com/developer/sdks/js/reference/Session.html#event:streamCreated) events if you prefer.
 
+
+### `preloadScript` Higher-Order 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 />`.
+
+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
+<Router>
+  <Route path="/">
+    <IndexRoute component="..." />
+    <Route path="something" component="..." />
+    <Route path="video" component={VideoChat} />
+    <Route path="something-else" component="..." />
+  </Route>
+</Router>
+```
+
+What you'd like to do is delay the loading of `opentok.js` until the `VideoChat` component is being used. Here's how you can do this:
+
+```javascript
+class VideoChat extends React.Component {
+  // All the code of your component
+}
+
+export default preloadScript(App);
+```
+
 ## Custom Build
 
 1. `git clone https://github.com/aiham/opentok-react.git`
@@ -282,6 +349,28 @@ Use of this helper is optional and you can instead use the `OTSession` component
 1. `npm run build`
 1. Check that files in `dist/` have been updated.
 
+## Contributing
+
+If you make changes to the project that you would like to contribute back then please follow the [contributing guidelines](CONTRIBUTING.md). All contributions are greatly appreciated!
+
 ## Tests
 
-TODO
+Run the unit tests locally with the following command:
+
+```
+npm run unit
+```
+
+By default this will launch the Chrome browser. To run tests in Firefox use:
+
+```
+npm run unit -- --browsers Firefox
+```
+
+Run the linter with:
+
+```
+npm run lint
+```
+
+The unit tests are automatically run on [Travis](https://travis-ci.org/aiham/opentok-react) on both Chrome and Firefox and the current build status is shown at the top of this document.

example/app.js

@@ -1,14 +1,15 @@
 import React from 'react';
-import ReactDOM from 'react-dom';
+import { render } from 'react-dom';
 
 import config from './config';
 import App from './components/App';
 
-OT.registerScreenSharingExtension('chrome', config.CHROME_EXTENSION_ID, 2);
-ReactDOM.render((
+render((
   <App
     apiKey={config.API_KEY}
     sessionId={config.SESSION_ID}
     token={config.TOKEN}
+    loadingDelegate={<div>Loading...</div>}
+    opentokClientUrl="https://static.opentok.com/v2/js/opentok.min.js"
   />
 ), document.getElementById('content'));

example/components/App.js

@@ -1,15 +1,17 @@
 import React, { Component } from 'react';
 
-import { OTSession, OTStreams } from '../../src'
+import { OTSession, OTStreams, preloadScript } from '../../src'
 import ConnectionStatus from './ConnectionStatus';
 import Publisher from './Publisher';
 import Subscriber from './Subscriber';
+import config from '../config';
 
-export default class App extends Component {
+class App extends Component {
   constructor(props) {
     super(props);
 
     this.state = {
+      error: null,
       connected: false
     };
 
@@ -23,14 +25,24 @@ export default class App extends Component {
     };
   }
 
+  componentWillMount() {
+    OT.registerScreenSharingExtension('chrome', config.CHROME_EXTENSION_ID, 2);
+  }
+
+  onError = (err) => {
+    this.setState({ error: `Failed to connect: ${err.message}` });
+  }
+
   render() {
     return (
       <OTSession
         apiKey={this.props.apiKey}
         sessionId={this.props.sessionId}
         token={this.props.token}
         eventHandlers={this.sessionEvents}
+        onError={this.onError}
       >
+        {this.state.error ? <div>{this.state.error}</div> : null}
         <ConnectionStatus connected={this.state.connected} />
         <Publisher />
         <OTStreams>
@@ -40,3 +52,5 @@ export default class App extends Component {
     );
   }
 }
+
+export default preloadScript(App);