Flywheel Extension SDK

Extend the Flywheel UI with custom applications.

Getting Started

Install with NPM

npm install @flywheel-io/extension

Initialize the extension and connect to Flywheel.

import { initExtension } from '@flywheel-io/extension';

initExtension().then(extension => {
  console.log('Container Type:', extension.container.container_type);
  console.log('Container ID:', extension.container._id);
  console.log('File Name:', extension.file.name);
});

Load the UMD Module

As an alternative to bundling with NPM, the SDK can be loaded via script tag. The library is available on the Flywheel global variable.

<body>
  <pre id="content"></pre>
  <script src="https://cdn.flywheel.io/sdk/extension/flywheel-extension-0.14.3.min.js"></script>
  <script>
    Flywheel.initExtension().then(extension => {
      return extension.getFileText(extension.container, extension.file);
    }).then(text => {
      document.getElementById('content').innerText = text;
    });
  </script>
</body>

A Flywheel site admin can register an extension application on the Admin -> Applications page. Click the Register New Application button to associate container or file types to your application. The URL can point to a local development server until your app is ready and published to a public location.

Learn more about application registration in the Flywheel knowledge base.

Extension Interface

The Extension instance establishes the user, container, and file context of the extension. It also provides methods that interact with Flywheel to get containers in the hierarchy, retrieve file data, or save data back to Flywheel. Most of these methods return Promises, but some methods that are more involved (e.g. the uploadFile method) return an Observable that can be subscribed to.

extension.getContainer('session', extension.container.parents.session).then(session => {
  extension.uploadFile(session, fileInput.files[0]).subscribe({
    next: event => {
      if (event.type === 'progress') {
        console.log('uploaded', event.loaded, '/', event.total, 'bytes');
      }
      if (event.type === 'response') {
        console.log('upload complete');
        console.dir(event.file);
      }
    }
  });
});

Extension Scope

When initializing the extension and connecting to a Flywheel instance, your application is set to ReadOnly scope by default. This means that you're able to read data from Flywheel but cannot write data, such as setting custom information or uploading files. If you want to opt into write functionality, pass the ReadWrite scope option, along with a validateOrigin function, into initExtension. The validateOrigin function receives the origin of a connecting Flywheel instance and determines it as trusted or not.

initExtension({ scope: 'ReadWrite', validateOrigin: origin => origin.endsWith('flywheel.io') }).then(extension => {
  return extension.updateContainerInfo(extension.container, {
    set: {
      ProjectPolicy: {
        owner: 'me@flywheel.io',
        writable: true,
      }
    }
  })
});

Data Models

Models for Flywheel objects are described in the documentation. The most commonly-used of these are:

When this package is installed via NPM in a TypeScript project, these definitions are made available in your project's environment.