publisher

Background

Publisher is a tool for writing novel Spotfire visuals or embedding existing web applications in Spotfire. In both cases these web applications can be written using JavaScript or TypeScript and can take advantage of the many freely available frontend JS/TS libraries.

Publisher-based visuals can be embedded in Spotfire documents or they can be remotely hosted web applications that appear as new visual types in Spotfire.

The publisher FE code is written in TypeScript and is meant to provide a range of methods that let the developer interact with Spotfire as if they were interacting with a typical backend server. Most of the methods used to fetch or modify data from or in Spotfire return Promises which, when resolved, should provide the user with the information they require e.g.

// Fetch the first 10 rows in the view (after filtering and sorting).
publisher.fetchRows({ from: 0, count: 10 })
  .then(rows) => {
    console.log(rows);
  })
  .catch((error) => {
    console.error('Something bad happened', error);
  });

// or using ES6 await
try {
  const rows = await publisher.fetchRows({ from: 0, count: 10 });
  console.log(rows);
} catch (error) {
  console.error('Something bad happened', error);
}

Publisher should work in both Spotfire Analyst as well as WebPlayer, though there are a few features that are not available in Spotfire WebPlayer.

Hello World

Below there is an example of a very simple webapp utilizing Publisher to get the 'active configuration' for the visual.

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <script src='./publisher.min.js'></script>
  <title>Hello World</title>
</head>
<body>

<script>
publisher.whenReady()
  .then((e) => {
    console.log('Publisher is ready to use', e);
    return publisher.fetchActiveConfiguration({});
  })
  .then((activeConfiguration) => {
    console.log('Active configuration', activeConfiguration);
  })
  .catch ((error) => {
    console.error(error);
  });
</script>

</body>
</html>

The result of this app is not very impressive, however it demonstrates a few important points.

Publisher has a whenReady method that should (nearly) always be the first method that any application using Publisher should call. Once that has executed successfully all other methods defined in the Publisher API should be safe to call. Think of this as the Publisher equivalent of window.onload.
Nearly all Publisher methods return a Promise that, when resolved, should contain the output of the call to Spotifre. In the example above, after publisher has successfully initialized, the fetchActiveConfiguration method is invoked, which returns information about the data table, columns, marking configuration, sorting, linked data tables etc. for the visual in which the HTML is hosted.

Build the library

npm run build

Create the bundle

For production

npx webpack

For development

npx webpack --mode development --output-filename publisher.js

You can add to these things like:

--output <path>
--watch

Building for release.

When we build for a release we should do the following:

Make sure we are on the release/X.X.X branch.
Set the version numbers in package.json. This is best done using npm version e.g. npm version 4.0.0-18. This will create a commit, so be sure to push.
Transpile the typesscript npm run build
Create the bundle npx webpack
Create and switch to the build branch e.g. git checkout -b release/X.X.X.X.
Commit and push the build branch.

Testing

There is a test directory with a test app and Spotfire DXP to test lot of the publisher endpoints and events. To run the tests you need to serve the test directory at the following URL, http://localhost:9000. Using the python http server you could do the following:

cd test
python3 -m http.server 9000

Note that if you change the publisher FE code in any way, you must rebuild and copy the minified bundled (publisher.min.js) into the test directory.

Open the publisher-test.dxp. This should load the test app from test/index.html. Most of the tests can be run by hitting the 'Run' button. Some of the tests alter the document or data tables in such a way that we cannot reset, therefore rerunning tests would result in failure due to unexpected state. Tests that modify the state of the document unrecoverably are run with all the other buttons. After running any one of those tests, you must reopen the document to run further tests. There is quite a lot of output to the console for these tests should anything fail.

Below is a list of the publisher function/endpoints that we do not have test coverage for:

createOrUpdateModifySequenceColumn
fetchIdentityRegions
fetchLogo
fetchModifySequenceColumns
fetchRegionStats
markLogo
chemistryCalculatedProperties
chemistryDepiction
chemistryNearestNeighbors
chemistryNearestNeighborsCountColumn
chemistryPreferences
chemistryRGroupDecomposition
chemistryScaffold
chemistryStructureSearch
chemistryToolkits
cancelDataFunction
deleteDataFunction
fetchDataFunctionState
addColumnsFromJsonUri
createDataTableFromJsonUri
addRowsFromJsonUri
find
fingerprintContains
setHttps - Not sure how to test
submitTask
markValueGroupRows

Creating the documentation

We use typedoc to generate the documentation for publisher. This is configured via the typedoc.json file.

npx typedoc