Welcome to OpenFin Docs

Explore our guides, resources and references for building with OpenFin

Get Started

Platform API

Getting started

A Platform and its content can be launched both programmatically and via a Platform manifest. Here we will explain the mechanisms that allow Application Providers to start a Platform and launch content into that Platform . As a best practice, we recommend leveraging a custom Platform Provider rather than in a snapshot on the Platform manifest.

Use the Platform API to:

  • Launch a platform, create a window and add a view
  • Launch content in a view
  • Configure a layout
  • Save and restore a snapshot

System requirements

  • OpenFin CLI installed
  • Windows 10+, Mac for developer purposes

Usage

Launch a Platform

In order to use the API, your window must be a part of a manifest-launched platform. Let's launch one.
Copy the following manifest and save as app.json locally.

{
    "platform": {
        "uuid": "example_platform",
        "applicationIcon": "https://openfin.github.io/golden-prototype/favicon.ico",
        "autoShow": false,
        "defaultWindowOptions": {
            "cornerRounding": {
                "height": 10,
                "width": 10
            },
            "contextMenu": true
        }
    },
    "snapshot": {
        "windows": [
            {
                "defaultWidth": 600,
                "defaultHeight": 600,
                "layout": {
                    "content": [
                        {
                            "type": "stack",
                            "content": [
                                {
                                    "type": "component",
                                    "componentName": "view",
                                    "componentState": {
                                        "name": "component_A1",
                                        "processAffinity": "ps_1",
                                        "url": "https://www.example.com"
                                    }
                                },
                                {
                                    "type": "component",
                                    "componentName": "view",
                                    "componentState": {
                                        "name": "component_A2",
                                        "url": "https://cdn.openfin.co/embed-web/chart.html"
                                    }
                                }
                            ]
                        }
                    ]
                }
            },
            {
                "defaultWidth": 600,
                "defaultHeight": 600,
                "defaultLeft": 200,
                "defaultTop": 200,
                "layout": {
                    "content": [
                        {
                            "type": "stack",
                            "content": [
                                {
                                    "type": "component",
                                    "componentName": "view",
                                    "componentState": {
                                        "name": "component_B1",
                                        "url": "https://openfin.co"
                                    }
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    },
    "runtime": {
        "arguments": "--v=1 --inspect",
        "version": "stable"
    },
    "shortcut": {
        "company": "OpenFin",
        "description": "OpenFin Platforms Prototype",
        "icon": "https://openfin.github.io/golden-prototype/favicon.ico",
        "name": "OpenFin Platforms Prototype"
    }
}

Now let's launch it!

openfin -l -c app.json

Seed project

Alternatively, you can launch our Platform App Seed project by cloning it then...

//Install dependecies then start
npm install

npm start

Create a platform window

Now that we have our platform, let's create a new platform window, along with a platform view, using Platform.createWindow.
Open your developer console from a platform view and enter the following code:

let platform = await fin.Platform.getCurrent();
let myWinIdentity = await platform.createWindow({
    contextMenu: true,
    layout: {
        content: [{
            type: 'stack',
            content:[{
                type: 'component',
                componentName: 'view',
                componentState: {
                    name: 'my-new-test-view',
                    url: 'http://www.example.com' // The URL of the View
                }
            }]
        }]
    }
});

Add a view to an existing window

From the same view (and console), lets add an additional view to that window using Platform.createView()

// The `platform`and `myWinIdentity` here are the objects we captured in step above
platform.createView(
    { // View Configuration Options
        name: 'my-new-test-view-2',
        url:'http://www.example.com'
    }, 
    myWinIdentity // Target Identity
);

The Platform.createView leverages two arguments:

  • View configuration options: the name, URL of the window and any other view options
  • Target identity: the identity of the window to which the view will be attached.

NOTE

You do not need to set a name for a view. Views that are not passed a name get a randomly generated one.

Launch content in a view

Content can be launched via manifest by calling the launchContentManifest() method on a wrapped platform instance. If the manifest to be launched contains a snapshot object, that snapshot is launched.

API calls

Once a platform is launched and running, snapshots can be launched into the platform using applySnapshot. Content can also be launched into the platform by manifest using startFromManifest. If that manifest also contains a snapshot object, that snapshot is launched. Any view specified in the snapshot is assigned a randomly generated name to avoid collisions.

applySnapshot(): A snapshot creates any windows and Vviews that are not running in the snapshot object.

// Get a wrapped layout platform instance
const platform = await fin.Platform.getCurrent();

const snapshot = {
    windows: [
        {
            layout: {
                content: [
                    {
                        type: 'stack',
                        content: [
                            {
                                type: 'component',
                                componentName: 'view',
                                componentState: {
                                    name: 'component_X',
                                    url: 'https://www.openfin.co'
                                }
                            },
                            {
                                type: 'component',
                                componentName: 'view',
                                componentState: {
                                    name: 'component_Y',
                                    url: 'https://cdn.openfin.co/embed-web/chart.html'
                                }
                            }
                        ]
                    }
                ]
            }
        }
    ]
}

platform.applySnapshot(snapshot);

createWindow(): creates a new platform window with default window UI

const platform = fin.Platform.getCurrentSync();
platform.createWindow({
    layout: {
        content: [
            {
                type: 'stack',
                content: [
                    {
                        type: 'component',
                        componentName: 'view',
                        componentState: {
                            name: 'test_view_1',
                            url: 'https://cdn.openfin.co/docs/javascript/canary/Platform.html'
                        }
                    },
                    {
                        type: 'component',
                        componentName: 'view',
                        componentState: {
                            name: 'test_view_2',
                            url: 'https://cdn.openfin.co/docs/javascript/canary/Platform.html'
                        }
                    }
                ]
            }
        ]
    }
}).then(console.log);

createView(): Creates a new platform view and attaches it to a specified target window.

let windowIdentity;
if (fin.me.isWindow) {
    windowIdentity = fin.me.identity;
} else if (fin.me.isView) {
    windowIdentity = (await fin.me.getCurrentWindow()).identity;
} else {
    throw new Error('Not running in a platform View or Window');
}

const platform = fin.Platform.getCurrentSync();

platform.createView({
    name: 'test_view',
    url: 'https://developers.openfin.co/docs/platform-api'
}, windowIdentity).then(console.log);

Deep linking (fin / fins link)

The RVM permits deep linking to an OpenFin application from anywhere that can invoke a “link” like a browser, email client, or another OpenFin application. The RVM uses a custom protocol handler to invoke an application, if not already running, and pass context to a specific location within an OpenFin application via a uniform resource identifier (URI).

You can use a fins link to both start a platform and to launch content into a platform. A link that targets a single platform manifest starts the platform, if the platform is not already running, and launches a snapshot into the platform, if present in the manifest.

You can also designate a separate content manifest to be launched into the platform by targeting the platform manifest and adding an $$appManifestUrl parameter. This starts the platform, if not already running, but launches the content in the second manifest at the $$appManifestUrl location. If an $$appManifestUrl parameter is included, any snapshot that exists on the platform manifest is ignored and only the content designated at the appManifestUrl is launched.

Like the launchContentManifest() method, if the manifest at the $$appManifestUrl location contains a snapshot object, that snapshot is launched. If instead it is a legacy manifest without a snapshot, the startup_app is launched as a single View in the Layout of a new OpenFin Window.

fins://mydomain.com/path-to-platform-manifest/app.json?$$appManifestUrl=https://mydomain.com/path-to-content-manifest/

NOTE

If both snapshot and startup_app object are present in the $$appManifestUrl location, the following hierarchy of which of these is used applies:

startup_app is always used if you are launching the manifest in a traditional way through the RVM.
snapshot is used only if the manifest is being passed via the $$appManifestUrl.

Configure a layout

OpenFin platforms allow end-users the freedom to easily move views within an OpenFin window to create their own customized workspace. Application providers may also wish to have presets that launch multiple views in a pre-configured window arrangement. Use our Configuration Generation Tool to create and arrange views for your own custom platform window layout and copy the corresponding JSON to apply to your platform app. Here we cover three basic layout configurations for tabs, columns and rows and a grid.

Example OpenFin Layout, click the image to zoom in.

Example OpenFin Layout, click the image to zoom in.

Tabs

//A window object within a snapshot that has one tabset (or “stack”) with three views
represented as tabs.
{
  "content": [
    {
      "type": "stack",
      "content": [
        {
          "type": "component",
          "componentName": "view",
          "componentState": {
            "name": "component_E",
            "url": "https://cdn.openfin.co/embed-web/chart.html"
          }
        },
        {
          "type": "component",
          "componentName": "view",
          "componentState": {
            "name": "component_F",
            "url": "https://openfin.co"
          }
        },
        {
          "type": "component",
          "componentName": "view",
          "componentState": {
            "name": "component_G",
            "url": "https://www.example.com"
          }
        }
      ]
    }
  ]
}

Columns and rows

//A window object within a layout that has three views arranged as columns.
"content": [
  {
    "type": "row",
    "content": [
      {
        "type": "component",
        "componentName": "view",
        "componentState": {
          "name": "component_C",
          "url": "https://cdn.openfin.co/embed-web/chart.html"
        }
      },
      {
        "type": "component",
        "componentName": "view",
        "componentState": {
          "name": "component_D",
          "url": "https://openfin.co"
        }
      },
      {
        "type": "component",
        "componentName": "view",
        "componentState": {
          "name": "component_E",
          "url": "https://www.example.com"
        }
      }
    ]
  }
]

Grid

//A window object within a snapshot that has four views arranged as a 2x2 grid.
{
  "content": [
    {
      "type": "row",
      "content": [
        {
          "type": "row",
          "content": [
            {
              "type": "column",
              "content": [
                {
                  "type": "component",
                  "componentName": "view",
                  "componentState": {
                    "name": "component_A",
                    "url": "https://cdn.openfin.co/embed-web/chart.html"
                  }
                },
                {
                  "type": "component",
                  "componentName": "view",
                  "componentState": {
                    "name": "component_B",
                    "url": "https://cdn.openfin.co/embed-web/chart.html"
                  }
                }
              ]
            }
          ]
        },
        {
          "type": "row",
          "content": [
            {
              "type": "column",
              "content": [
                {
                  "type": "component",
                  "componentName": "view",
                  "componentState": {
                    "name": "component_C",
                    "url": "https://www.example.com"
                  }
                },
                {
                  "type": "component",
                  "componentName": "view",
                  "componentState": {
                    "name": "component_D",
                    "url": "https://www.openfin.co"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Snapshots

Earlier, we loaded a brand-new Platform Window with two Views in it. Here we will retrieve getSnapshot a Platform Layout and apply applySnapshot a previously saved Platform layout.

Get snapshot

Use the following code in the same console you were using in the Add a View to an Existing Window. Platform.getSnapshot returns a snapshot object and can be used to return the desktop back to this current state. You can store this object wherever you'd like, and use it later to apply this Snapshot.

// The `platform` here is the object we captured
const mySnapshot = await platform.getSnapshot();
console.log(mySnapshot);

Apply snapshot

Now let’s use our snapshot object to recreate our desktop using applySnapshot. First, rearrange your platform windows on your desktop.

  1. Close the window you created earlier (the one filled with www.example.com Views), move your windows to different locations.
  2. Move the views in their platform windows to different locations.
  3. Execute the code below to get your desktop back to the way it was before.

Platform manifest

Here we will breakdown the various pieces of the OpenFin platform manifest file.

platform: Defines the platform as a targetable unique entity. Requires a top-level platform property and a UUID. If you are previous accustomed to OpenFin manifest structure, platform acts in the same way as your startup_app field.

{
    "runtime": {
      ...
    },
    "shortcut": {
      ...
    },
    "platform": {
        "uuid": "platform-example",
        "defaultWindowOptions": {
            "stylesheetUrl": "full-url-to-css-sheet",
            "cornerRounding": {
                "height": 10,
                "width": 10
            }
        }
    }
}

snapshot: Defines the window and view configurations to be launched into a platform. If a snapshot is defined as a top-level option in your platform manifest, the platform launches with that snapshot by default. It has a windows property that contains an array of OpenFin Window objects. Windows should not be given names, because they can be destroyed and re-created by the user at any time.

{
    "snapshot": {
       "windows": [
            {
                "defaultWidth": 600,
                "defaultHeight": 600,
                "layout": {
                    ...
                }
            }
        ]
    }
}

layout: Defines the layout configuration for a window. To position an OpenFin view within a window, your layout must contain a content declaration with a componentName of view. Content items have a "type" property, which can have the following values: "row", "column", "stack", or "component". Arrays of content items can be nested within other content items as well.

{
    "snapshot": {
        "windows": [
            {
                "defaultWidth": 600,
                "defaultHeight": 600,
                "layout": {
                    "content": [
                        {
                            "type": "stack",
                            "content": [
                                {
                                    "type": "component",
                                    "componentName": "view",
                                    "componentState": {
                                        ...
                                    }
                                },
                                {
                                    "type": "component",
                                    "componentName": "view",
                                    "componentState": {
                                        ...
                                    }
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

componentState: Defines the componentState property to provide the OpenFin view options. A url manifest that contains View Options can additionally be added as a manifestUrl property. Properties in the manifest will take precedence if there is any collision.

{
    "snapshot": {
        "windows": [
            {
                "defaultWidth": 600,
                "defaultHeight": 600,
                "layout": {
                    "content": [
                        {
                            "type": "stack",
                            "content": [
                                {
                                    "type": "component",
                                    "componentName": "view",
                                    "componentState": {
                                        "name": "component_A1",
                                        "processAffinity": "ps_1",
                                        "url": "https://www.example.com"
                                    }
                                },
                                {
                                    "type": "component",
                                    "componentName": "view",
                                    "componentState": {
                                        "name": "component_A2",
                                        "url": "https://cdn.openfin.co/embed-web/chart.html"
                                    }
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Updated 24 days ago


Platform API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.