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.

  1. First, copy the JSON below, paste it into your IDE of choice, and save it as app.json.
  2. Next, open your terminal, navigate to the folder containing your app.json file, 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.

  1. Open up the developer console from one of your Platform Views.
  2. Paste the following code into your console
  3. Press enter. You should see a new Platform Window appear, with http://www.example.com displayed 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.Example OpenFin Layout, click the image to zoom in.

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 type below from row to column and 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"
                                    }
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Did this page help you?