IMPORTANT NOTE: The code in this repo has now been deprecated as it has been replaced by our new Excel integration. Please refer to the developer docs for more information.
This repo provides a demonstration of the OpenFin Excel Service and its JavaScript API.
Note: This main source code for this demo is intentionally coded in plain JavaScript so that its easy to follow, without any need to understand other technologies/ frameworks. The API libraries are generated from TypeScript, and the end-product utilizes webpack to achieve a single-file web application.
This demo uses ExcelDna to create the Excel addin.
- Download and run the installer:
-
After the installer runs, the OpenFin application should launch and either connect to Excel if it already running or present the option to launch Excel.
-
Once Excel is running you can create workbooks or open existing workbooks and observe two-way data synchronization between Excel and the demo app.
For development purposes you may wish to clone this repository and run on a local computer. The Excel Add-In is only compatible with Excel for Windows.
Pre-requisite: Node and NPM must be installed ( https://nodejs.org/en/ ).
Clone the repository and, in the Command Prompt, navigate into the excel-api-example directory created.
In the Command Prompt run:
> npm install
Once the Node packages have installed, it is now possible to make modifications to files in the excel-api-example\src folder and rebuild the project by running:
> npm run webpack
After rebuilding, start the application by running:
> npm start
This will start a simple HTTP server on port 8080 and launch the OpenFin App automatically.
Declare the Excel Service by including the following declaration in your application manifest:
"services":
[
{ "name": "excel" }
]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:
<script src="https://openfin.github.io/excel-api-example/client/fin.desktop.Excel.js"></script>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
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();await fin.desktop.ExcelService.init();It is advisable to place this call before any calls on the fin.desktop.Excel namespace.
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:
var sheet1 = fin.desktop.Excel.getWorkbookByName('Book1').getWorksheetByName('Sheet1');
// A little fun with Pythagorean triples:
sheet1.setCells([
["A", "B", "C"],
[ 3, 4, "=SQRT(A2^2+B2^2)"],
[ 5, 12, "=SQRT(A3^2+B3^2)"],
[ 8, 15, "=SQRT(A4^2+B4^2)"],
], "A1");
// Write the computed values to console:
sheet1.getCells("C2", 0, 2, cells => {
console.log(cells[0][0].value);
console.log(cells[1][0].value);
console.log(cells[2][0].value);
});Monitoring various application, workbook, and sheet events are done via the addEventListener functions on their respective objects. For example:
sheet1.getCells("C2", 0, 2, cells => {
var lastValue = cells[0][0].value;
fin.desktop.Excel.addEventListener('afterCalculation', () => {
sheet1.getCells("C2", 0, 2, cells => {
if(cells[0][0].value !== lastValue) {
console.log('Value Changed!');
}
lastValue = cells[0][0].value;
});
});
})Version 1 of the Demo API utilized callbacks to handle asynchronous actions and return values. Starting in Version 2, all asynchronous functions are instead handled via Promises, however, for reverse compatibility the legacy callback-style calls are still supported.
All functions which return promises can also take a callback as the final argument. The following three calls are identical:
// Version 1 - Callback style [deprecated]
fin.desktop.Excel.getWorkbooks(workbooks => {
console.log('Number of open workbooks: ', workbooks.length);
});
// Version 2 - Promise then callback
fin.desktop.Excel.getWorkbooks().then(workbooks => {
console.log('Number of open workbooks: ', workbooks.length);
});
// Version 2 - Promise await
var workbooks = await fin.desktop.Excel.getWorkbooks();
console.log('Number of open workbooks: ', workbooks.length);The complete Excel Service API Documentation is available here.
In the future, type definition files will be available for public consumption via an NPM types package.
MIT
The code in this repository is covered by the included license.
However, if you run this code, it may call on the OpenFin RVM or OpenFin Runtime, which are covered by OpenFin’s Developer, Community, and Enterprise licenses. You can learn more about OpenFin licensing at the links listed below or just email us at [email protected] with questions.
https://openfin.co/developer-agreement/
https://openfin.co/licensing/
Please enter an issue in the repo for any questions or problems. Alternatively, please contact us at [email protected]