Update the readme with more accurate information/documentation/and in…

…fo about Mocha tests. Issue jellyfin-archive#50

.github/pull_request_template.md

@@ -28,6 +28,6 @@ Thanks!
 
 - [ ] I've updated the documentation as necessary
 - [ ] If this Pull Request resolves an issue, I linked to the issue in the text above (and used the correct [keyword to close issues using keywords](https://help.github.com/articles/closing-issues-using-keywords/))
-- [ ] I've run `npm run test` and no errors were found (run `npm style` to auto-fix errors it can)
-- [ ] I've run the `test-framework` tests for Android (See Readme)
+- [ ] I've run `npm test` and no errors were found (run `npm style` to auto-fix errors it can)
+- [ ] I've run the tests (See Readme)
 - [ ] I added automated test coverage as appropriate for this change

README.md

@@ -1,88 +1,112 @@
 <h1 align="center">cordova-plugin-chromecast</h1>
-<h3 align="center">Chromecast in Cordova</h3>
+<h3 align="center">Control Chromecast from your Cordova app</h3>
 
-## Installation
-Add the plugin with the command below in your cordova project directory.
+# Installation
 
 ```
 cordova plugin add https://github.com/jellyfin/cordova-plugin-chromecast.git
 ```
 
-## Usage
+# Usage
 
-This project attempts to implement the official Google Cast SDK for Chrome within Cordova. We've made a lot of progress in making this possible, so check out the [offical documentation](https://developers.google.com/cast/docs/chrome_sender) for examples.
+This project attempts to implement the [official Google Cast API for Chrome](https://developers.google.com/cast/docs/reference/chrome/) within the Cordova webview.  
+This means that you should be able to write almost identical code in cordova as you would if you were developing for desktop Chrome.  
 
-When you call `chrome.cast.requestSession()` a popup will be displayed to select a Chromecast. 
+We have not implemented every function in the [API](https://developers.google.com/cast/docs/reference/chrome/) but most of the core functions are there.  If you find a function is missing we welcome [pull requests](#contributing)!  Alternatively, you can file an [issue](https://github.com/jellyfin/cordova-plugin-chromecast/issues), please include a code sample of the expected functionality if possible!
 
-Calling `chrome.cast.requestSession()` when you have an active session will display a popup with the option to "Stop Casting".
+The only significant difference between the [cast API](https://developers.google.com/cast/docs/reference/chrome/) and this plugin is the initialization.
 
-**Specific to this plugin** (Not supported on desktop chrome)
+In **Chrome desktop** you would do:
+```js
+window['__onGCastApiAvailable'] = function(isAvailable, err) {
+  if (isAvailable) {
+    // start using the api!
+  }
+};
+```
 
-To make your own custom route selector use this:
+But in **cordova-plugin-chromecast** you do:
+```js
+document.addEventListener("deviceready", function () {
+  // start using the api!
+});
 ```
+
+## Specific to this plugin
+We have added some additional methods beyond the [Chromecast API]((https://developers.google.com/cast/docs/reference/chrome/)).  
+They can all be found in the `chrome.cast.cordova` object. 
+
+To make your own **custom route selector** use this:
+```js
 // This will begin an active scan for routes
 chrome.cast.cordova.scanForRoutes(function (routes) {
   // Here is where you should update your route selector view with the current routes
   // This will called each time the routes change
+  // routes is an array of "Route" objects (see below)
 });
 
 // When the user selects a route
 // stop the scan to save battery power
 chrome.cast.cordova.stopScan();
+
 // and use the selected route.id to join the route
 chrome.cast.cordova.selectRoute(route.id, function (session) {
   // Save the session for your use
 }, function (err) {
-
+  // Failed to connect to the route
 });
 
 ```
 
-## Status
+**Route** object
+```text
+id             {string}  - Route id
+name           {string}  - User friendly route name
+isCastGroup    {boolean} - Is the route a cast group?
+isNearbyDevice {boolean} - Is it a device only accessible via guest mode?
+                           (aka. probably not on the same network, but is nearby and allows guests)
+```
+
 
-The project is now pretty much feature complete - the only things that will possibly break are missing parameters. We haven't done any checking for optional paramaters. When using the plugin make sure your constructors and function calls have every parameter you can find in the method declarations.
+# Plugin Development
 
-<h3 align="center">Plugin Development<h3>
+## Setup
 
-* Link your local copy of the the plugin to a project for development and testing
-  * With admin permission run `cordova plugin add --link <relative path to the plugin's root dir>`
-* This links the plugin's **java** files directly to the Android platform.  So you can modify the files from Android studio and re-deploy from there.
-* Unfortunately it does **not** link the js files.
-* To update the js files you must run:
-    * `cordova plugin remove <plugin-name>`
-    * `cordova plugin add --link <relative path to the plugin's root dir>`
-        * Don't forget the admin permission
-    * Or, you can follow these [hot reloading js instructions](https://github.com/miloproductionsinc/cordova-testing#hot-reload-js)
+Follow these direction to set up for plugin development:
 
-## Formatting
+* You will need an existing cordova project or [create a new cordova project](https://cordova.apache.org/#getstarted).
+* With **admin permission** run: `cordova plugin add --link <relative path to the plugin's root dir>`
 
-* Run `npm run style` (from the plugin directory)
-  * If you get `Error: Cannot find module '<project root>\node_modules\eslint\bin\eslint'`
-    * Run `npm install`
-  * If it finds any formatting errors you can try and automatically fix them with:
-    * `node node_modules/eslint/bin/eslint <file-path> --fix`
-  * Otherwise, please manually fix the error before committing
+### About the `--link` flag
+The `--link` flag allows you to modify the native code (java/swift/obj-c) directly in the relative platform folder if desired.
+  * This means you can work directly from Android Studio/Xcode!
+  * Note: Be careful about adding and deleting files.  These changes will be exclusive to the platform folder and will not be transferred back to your plugin folder.
+  * Note: The link only works for native files.  Other files such as js/css/html/etc must **not** be modified in the platform folder, these changes will be lost.
+    * To update the js/css/html/etc files you must run:
+        * `cordova plugin remove <plugin-name>`
+        * With **admin permission**: `cordova plugin add --link <relative path to the plugin's root dir>`
 
 ## Testing
 
-**1)** 
+### Code Format
 
-Run `npm test` to ensure your code fits the styling.  It will also pick some errors.
+Run `npm test` to ensure your code fits the styling.  It will also find some errors.
 
-**2)**
+  * If errors are found, you can try running `npm run style`, this will attempt to automatically fix the errors.
 
-This plugin has [cordova-plugin-test-framework](https://github.com/apache/cordova-plugin-test-framework) tests.
+### Tests
 
-To run these tests you can follow [these instructions](https://github.com/miloproductionsinc/cordova-testing).
+How to run the tests:
+* With **admin permission** run `cordova plugin add --link <relative path to the plugin's root dir>/tests`
+* Change `config.xml`'s content tag to `<content src="plugins/cordova-plugin-chromecast-tests/www/tests.html" />`
+* You must a valid chromecast on your network to run the tests.
+* Run the app, let auto tests do its thing, and then follow the directions for manual tests.
 
-NOTE: You must run these tests from a project with the package name `com.miloproductionsinc.plugin_tests` otherwise `SPEC_00310` will fail.  (It uses a custom receiver which are only allowed receive from one package name.)
-
-  * You can temporarily rename the project you are testing from:
-    * config.xml > `<widget id="com.miloproductionsinc.plugin_tests"`
-  * Or clone this project https://github.com/miloproductionsinc/cordova-testing
+[Why we chose a non-standard test framework](https://github.com/jellyfin/cordova-plugin-chromecast/issues/50)
 
 
 ## Contributing
 
-* Make sure all tests pass
-* Preferably, write a test for your contribution if applicable (for a bug fix, new feature, etc)
+* Make sure all tests pass ([Code Format](#code-format) and [Tests](#tests))
+* Write a test for your contribution if applicable (for a bug fix, new feature, etc)
+* Update documentation as necessary

www/chrome.cast.js

@@ -1061,6 +1061,7 @@ chrome.cast.cordova = {
      * active routes whenever a route change is detected.
      * It is super important that client calls "stopScan", otherwise the
      * battery could drain quickly.
+     * https://github.com/jellyfin/cordova-plugin-chromecast/issues/22#issuecomment-530773677
      * @param {function(routes)} successCallback
      * @param {function(chrome.cast.Error)} successCallback
      */