Getting Started - Platform
Requirements
- OpenFin CLI installed
- OpenFin Runtime 15.80.49.30+
- Windows Operating System | Mac not fully supported and may result in unexpected behavior
Launching a Platform
In order to use the API, your window must be a part of a manifest-launched Platform. Let's launch one.
- First, copy the JSON below, paste it into your IDE of choice, and save it as
app.json. - Next, open your terminal, navigate to the folder containing your
app.jsonfile, and run the following command to launch your Platform.
Shell example
openfin -l -c app.json
Try dragging the tabs within a window to reposition the views, or drag onto another window's tabset to move the view to a new window.
JSON example
Click on JSON and copy the code shown.
Save it as app.json, and launch that app.json with the following command:
openfin -l -c app.json
{
"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"
}
}
Further details on the Platform Manifest structure, see Manifest JSON Structure.
Creating a Platform Window
Now that we have our Platform, let's create a new Window, along with a View, using the Platform API call createWindow.
- Open up the developer console from one of your Platform Views.
- Paste the following code into your console
- Press enter. You should see a new Platform Window appear, with
http://www.example.comdisplayed within it.
JavaScript example
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
}
}]
}]
}
});
Adding a Platform View to an Existing Window
Now that we have a new Platform Window, let's add an additional View to that Window.
Paste the following code into the same console you were previously using. The createView function takes 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
You should see an additional View appear in the Window you just created.
Note
You do not need to set a name for a View. Views that are not passed a name get a randomly generated one.
JavaScript example
// The `platform`and `myWinIdentity` here are the objects we captured in step 2
platform.createView(
{ // View Configuration Options
name: 'my-new-test-view-2',
url:'http://www.example.com'
},
myWinIdentity // Target Identity
);
Configuration Generation Tool
The Platform object in the Application Config is extensively customizable and can lead to a lot of upfront JSON. To assist in getting started, we've provided a Configuration Generation tool to facilitate the creation of your first Platform window.
Diving deeper
OpenFin Views
At the core of Platforms is a separation between content and windowing. Content (a web application) is loaded into an OpenFin View which is then attached to a window. Views have their own JavaScript context that is distinct and unconnected to the window’s context, that have no DOM representation within the window. This allows views to move between windows without refreshing or otherwise destroying the context.
Note
Views have no windowing functionality of their own. They must be attached to a window, and given bounds relative to that window, in order to display their content. Unlike IFrames, Views can be moved between windows without refreshing, and can be used to display non-embeddable content.
Views are accessed via the fin.View API. However, when using OpenFin Platforms, please use the fin.Platform API as much as possible.
Note
Native JavaScript window.open is not currently supported in views.
You can perform any custom initialization before calling fin.Platform.init:
Example Layouts
Example OpenFin Layout, click the image to zoom in.
OpenFin's Platforms allows 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. Below are some examples of pre-configured view arrangements:
Note
Top-level content items cannot contain more than one element.
Columns or Rows
In the JSON tab, you will find an example JSON of 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"
}
}
]
}
]
Note
Please note that components inside a row will show up as columns. There is no need to nest the components in a “stack” item to create the header and tab indicator, this will be created automatically. To arrange them as rows instead, please swap the
typebelow fromrowtocolumnand vice versa.
Tabs
In the JSON tab, you will find an example JSON of 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"
}
}
]
}
]
}
Grid
In the JSON tab, you will find an example JSON of 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"
}
}
]
}
]
}
]
}
]
}
Platform Manifest JSON Structure
Below is an explanation and breakdown of the various pieces of the OpenFin Platform Manifest file. This is the file that defines how an OpenFin application works.
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 will launch 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.
Note
Remember, you can use the Configuration Generation tool as described previously to generate the JSON required for this object rather than writing it yourself.
{
"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. In version 16.83.53.*+, a url to a 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 over 1 year ago