npm package: @flywheel-io/extension
Description: Create extension applications for the Flywheel web UI
Author: Jody Zeitler
Latest version: 0.14.8

Flywheel Extension SDK
======================

Extend the Flywheel UI with custom applications.

Getting Started
---------------

### Install with NPM

```shell
npm install @flywheel-io/extension
```

Initialize the extension and connect to Flywheel.

```js
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.

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

### Registering Your Application

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](https://docs.flywheel.io/hc/en-us/articles/4403390314003).

Extension Interface
-------------------

The [Extension](https://cdn.flywheel.io/docs/extension/0.14.8/classes/Extension.html) 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](https://cdn.flywheel.io/docs/extension/0.14.8/classes/Extension.html#uploadFile) method) return an Observable that can be subscribed to.

```js
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](https://cdn.flywheel.io/docs/extension/0.14.8/interfaces/ExtensionOptions.html#validateOrigin) function receives the origin of a connecting Flywheel instance and determines it as trusted or not.

```js
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:
* [Container](https://cdn.flywheel.io/docs/extension/0.14.8/interfaces/Container.html)
* [File](https://cdn.flywheel.io/docs/extension/0.14.8/interfaces/File.html)
* [User](https://cdn.flywheel.io/docs/extension/0.14.8/interfaces/User.html)

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