Version 4.0 Update (#55)

* Updated release 4.0 (fixes for Excel RTD functionality, updated dependencies, logging and versioning information)

* Updated documentation for release 4.0

DOCS.md

@@ -10,14 +10,14 @@ Represents the helper service which manages OpenFin connections to running insta
 
 ### Properties
 
-```
+```javascript
 connected: Boolean // indicates that OpenFin is connected to the helper service
 initialized: Boolean // indicates that the current window is subscribed to Excel service events
 ```
 
 ### Functions
 
-```
+```javascript
 /*
 init();
 Returns a promise which resolves when the Excel helper service is running and initialized.
@@ -32,7 +32,7 @@ Represents a single instance of an Excel application.
 
 ### Functions
 
-```
+```javascript
 
 /*
 getWorkbooks();
@@ -101,7 +101,7 @@ removeEventListener("workbookAdded", handler);
 
 ### Events
 
-```
+```javascript
 {type: "connected"};
 // is fired when excel connects to Openfin.
 //Example:
@@ -147,7 +147,7 @@ name: String // name of the workbook that the object represents.
 
 ### Functions
 
-```
+```javascript
 /*
 getWorksheets();
 Returns a promise which resolves an array of worksheets in the current workbook.
@@ -199,7 +199,7 @@ await workbook.close();
 
 ### Events
 
-```
+```javascript
 {type: "sheetAdded", target: ExcelWorkbook, worksheet: ExcelWorksheet};
 //fired when a new sheet is added to the workbook
 //Example:
@@ -253,7 +253,7 @@ workbook: fin.desktop.ExcelWorkbook // workbook object that worksheet belongs to
 
 ### Functions
 
-```
+```javascript
 /*
 setCells(values, offset);
 Asynchronously populates the cells with the values starting from the provided cell reference and returns a promise which resolves when the operation is complete.
@@ -414,7 +414,7 @@ await sheet.formatRange("A1:E:10", {
 
 ### Events
 
-```
+```javascript
 {type: "sheetChanged", target: ExcelWorksheet,  data: {column: int, row: int, formula: String, sheetName: String, value:String}};
 //fired when any cell value in the sheet has changed.
 //Example:
@@ -491,6 +491,23 @@ rtd.setValue('Topic1', 123.55);
 
 ```
 
+### Excel RTD Functionality (New in 4.0.0)
+
+From version 4.0 you can dispose the rtd instance that you created. You have the option of specifying whether or not you want pushed values cleared (as you may want some rtd instances to behave differently). You should call dispose if your application is closing or if you no longer need the functionality.
+
+```javascript
+const rtd = await fin.desktop.ExcelService.createRtd('Provider1');
+
+// Will stop listening to excel and will tell excel to clear all values in the connected topics
+ await rtd.dispose();
+
+// OR
+
+// Will stop listening to excel and but will NOT tell excel to clear all values in the connected topics
+ await rtd.dispose(false);
+
+```
+
 ### Excel Self Hosting
 
 You may wish to control the version of the excel service you are using and self host it.

LOGS.md

@@ -0,0 +1,36 @@
+# OpenFin Excel API Logs
+
+## From Version 4
+
+### Client Logs
+
+From version 4.0 onwards you can pass true to the init function and it will enable logging (you will see the excel api console.log entries). 
+
+```javascript
+await fin.desktop.ExcelService.init(true);
+```
+
+If you wish to add these logs to your own logging setup you can pass an object with the following implementation (the following is the Typescript interface to give you an idea):
+
+```javascript
+export interface ILog {
+    name?: string;
+    trace?: (message, ...args) => void;
+    debug?: (message, ...args) => void;
+    info?: (message, ...args) => void;
+    warn?: (message, ...args) => void;
+    error?: (message, error, ...args) => void;
+    fatal?: (message, error, ...args) => void;
+}
+```
+If you pass an object but do not provide a full implementation then we will use our default implementation that logs to the console for the functions that are not provided.
+
+This is to help with debugging if you wish to verify something.
+
+### Excel Provider Logs
+
+The excel provider will log information to a log file. If you go to your OpenFin/apps directory you should find the Excel-Service-Manager app and this should have an app.log file within it's folder.
+
+### Excel Helper/Plugin Logs
+
+These produce logs to help with debugging and can be found by going to your OpenFin\shared\assets\excel-api-addin\logging folder.

README.md

@@ -55,7 +55,7 @@ This will start a simple HTTP server on port 8080 and launch the OpenFin App aut
 
 Declare the Excel Service by including the following declaration in your application manifest:
 
-```
+```javascript
 "services":
 [
    { "name": "excel" }
@@ -66,27 +66,56 @@ Declare the Excel Service by including the following declaration in your applica
 
 Unlike other services, currently the Excel API client is only provided as a script tag. Include the following script tag on each page that requires API access:
 
-```
+```javascript
 <script src="https://openfin.github.io/excel-api-example/client/fin.desktop.Excel.js"></script>
 ```
 
 ## Waiting for the Excel Service to be Running
 
-During startup, an application which wishes to utilize the Excel Service should ensure the service is running and ready to receive commands by invoking:
+During startup, an application which wishes to utilize the Excel Service should ensure the service is running and ready to receive commands by doing *two* things:
+
+### Setup event listeners so you are notified when Excel is connected/disconnected before trying to interact with Excel
+```javascript
+async function onExcelConnected(data) {
+  console.log("Excel Connected: " + data.connectionUuid);
+  let connected = await window.fin.desktop.Excel.getConnectionStatus();
+  console.log("Connected: " + connected);
 
+  // do some work with the excel api
+}
+
+async function onExcelDisconnected(data) {
+  console.log("Excel Disconnected: " + data.connectionUuid);
+}
+
+function initializeExcelEvents() {
+  console.log("Initialising excel connected/disconnected events");
+  fin.desktop.ExcelService.addEventListener("excelConnected", onExcelConnected);
+  fin.desktop.ExcelService.addEventListener("excelDisconnected", onExcelDisconnected);
+}
+initializeExcelEvents();
 ```
+
+### Invoke the Excel service after setting up your listeners by invoking:
+
+```javascript
 await fin.desktop.ExcelService.init();
 ```
 
 It is advisable to place this call before any calls on the `fin.desktop.Excel` namespace.
 
+## New Support Capabilities from Version 4.0+
+
+- [Logging](LOGS.md)
+- [Versioning Information](VERSIONS.md)
+
 # Getting Started with the API
 
 ## Writing to and Reading from a Spreadsheet:
 
 After a connection has been established between Excel and the OpenFin application, pushing data to a spreadsheet and reading back the calculated values can be performed as follows:
 
-```
+```javascript
 var sheet1 = fin.desktop.Excel.getWorkbookByName('Book1').getWorksheetByName('Sheet1');
 
 // A little fun with Pythagorean triples:
@@ -110,7 +139,7 @@ sheet1.getCells("C2", 0, 2, cells => {
 
 Monitoring various application, workbook, and sheet events are done via the `addEventListener` functions on their respective objects. For example:
 
-```
+```javascript
 sheet1.getCells("C2", 0, 2, cells => {
   var lastValue = cells[0][0].value;
 
@@ -132,7 +161,7 @@ Version 1 of the Demo API utilized callbacks to handle asynchronous actions and
 
 All functions which return promises can also take a callback as the final argument. The following three calls are identical:
 
-```
+```javascript
 // Version 1 - Callback style [deprecated]
 fin.desktop.Excel.getWorkbooks(workbooks => {
   console.log('Number of open workbooks: ', workbooks.length);

VERSIONS.md

@@ -0,0 +1,25 @@
+# OpenFin Excel API Version Numbers
+
+## From Version 4
+
+### Client Version
+
+From version 4.0 onwards you can find out the client version (for log purposes etc) by logging:
+
+```javascript
+fin.desktop.Excel.version;
+```
+
+### Excel Provider Version
+
+To confirm you are connecting to the ExcelService you expect you can log/check:
+
+```javascript
+fin.desktop.ExcelService.version;
+```
+
+### Excel Helper/Plugin Version
+
+From version 4 you and your end users can confirm you are using the right excel plugin version by looking at Excel. 
+
+The message will now say Connected to OpenFin (v x.x.x.x)