OpenFin

Layouts Service Configuration

Getting Started

A config attribute can be added within a service declaration to customize the behavior of the service. The service will apply any properties within this declaration to the application and all it’s child windows, without affecting any other applications running on the desktop.

{
  "startup_app": {
    "uuid": "my-app"
    . . .
  },
  . . .
  "services": [{
    "name": "layouts",
    "config": {
      "features": {
        "dock": false
      },
      "tabstrip": {
        "url": "http://localhost:8080/tabstrip.html",
        "height": 40
      }
    }
  }]
}

The above example sets a custom tabstrip and disables docking for the my-app application. This tabstrip will then be used for the application’s startup window and any child windows. Please find the properties available in the top-level config object below.

If a parent application includes Layouts in it’s app config, child applications programmatically launched without an app config will have layouts enabled and will need to be configured separately from the parent app. It will not inherit the parent applications configuration settings. Applications launched programmatically with an app config will act like any other application.

Property
Type
Description
Default

enabled

bool

Whether the Layouts service is enabled in the app noted in startup_app

true

features

{
“dock”: bool,

“snap”: bool,

“tab”: bool

}

Object representing each of the features that can be turned on or off in Layouts

All default to true (if layouts listed in app config)

tabstrip

{
“url”: string,

“height”: number

}

Object detailing the url and height for a custom tabstrip

Null (use layouts provided tabstrip)

Using Rules

The above example shows how to set configuration that applies to the whole application. It is also possible to use rules to selectively apply Layouts configuration to certain windows, or to applications with a different uuid.

An app config can contain an arbitrary number of rules. Each rule consists of a set of properties, and a filter that specifies what entities that configuration applies to. Within an app config, it is possible to write rules that apply to both applications and windows. Any application-scope rule will automatically apply to all windows that belong to that application. If an application that includes Layouts in it’s app config is to launch any “child” apps programmatically without an app config, then that application will be included in all layouts functionality unless it is disabled.

The example below defines three rules, each demonstrating a different use-case:

  • Exclude a programmatically launched application from the service De-register an application from the service: the app-launcher application (including all its child windows) will be completely excluded from all service functionality.

  • Exclude a set of child windows from the service These windows can be identified based on application-specific window naming conventions, which allows a regex expression to exclude these windows.

  • Exclude a set of child windows from tabbing with other windows In this example these are small, fixed-size tool windows that should dock with other windows, but we don’t want them to be able to tab-into application windows.

{
  "startup_app": {
    "uuid": "my-app"
    // . . .
  },
  // . . .
  "services": [{
    "name": "layouts",
    "config": {
      "features": {
        "dock": false
      },
      "tabstrip": {
        "url": "http://localhost:8080/tabstrip.html",
        "height": 40
      },
      "rules": [
        {
          "scope": {
            "level": "application",
            "uuid": "app-launcher"
          },
          "config": {"enabled": false}
        },
        {
          "scope": {
            "level": "window",
            "uuid": "my-app",
            "name": {"expression": "context-menu-.*"}
          },
          "config": {"enabled": false}
        },
        {
          "scope": {
            "level": "window",
            "uuid": "my-app",
            "name": {"expression": "toolbox-.*"}
          },
          "config": {
            "features": {
              "tab": false
            }
          }
        }
      ]
    }
  }]
}

The rules property is made up of an array of Rule Objects. A Rule Object has two top-level properties, scope and config.

Rule object

Property Type Description
scope <Scope Object> Scope / Target application or window for the rule object
config <Config Object> Configuration settings for the rule object

The scope type can be either an application or window and will require a uuid and optionally a name (if a window type).

Scope object

Property Type Description Notes
level "application" "window"
uuid string Uuid of the target application or window for the rule Mandatory
name string Name of the target window for the rule Only necessary for "window" rule types

Config lifecycle

Lifecycle basics

Every piece of configuration has an attached lifecycle. Any configuration defined within an app config will be unloaded when that application and any child applications exit. For this reason, care should be taken when defining rules that apply to an application other than the one defined within the app config. Wherever possible, configuration for an application should be specified in that app’s config.

Applications launched programmatically

Wherever possible, config for an application should be specified in that app’s config. This isn’t always possible as not all applications are launched from a manifest. In these cases, we advise pushing up any configuration data into the app config of the parent application. Child applications launched without an app config will have Layouts fully enabled if not separately configured, regardless of any configuration in the parent application.

Best practices

The above configuration mechanisms have been kept purposely flexible, in order to accommodate as many use-cases as possible. It is expected that users of the service will inevitably have business requirements that can’t feasibly be accommodated by a service designed for general-purpose usage.

We advise following the below list of best practices, to ensure consistent behavior and maximum forward-compatibility:

  • Where possible, always launch any layouts-enabled applications from an app config (rather than fin.Application.create).
  • Where possible, always define any config within the manifest for the affected application/window(s).
  • When defining rules that cross application boundaries, ensure that these rules only point “down” the application hierarchy.

The above best practices are illustrated in the following diagram:

  • Each application launched from an app config contains its own Layouts configuration.
  • Any application that was launched programmatically is configured by placing rules in the closest parent application app config.

Supported options

Note that the available configuration options are determined by the version number of the service provider, not the version of the client that is embedded in your application. This means that any additional options added in future releases can be used by your application without needing to update your project dependencies or re-building/deploying the application.

Future versions of the service may add additional configuration options, but these versions will always be backward-compatible when using a provider of the same major version (as per semver conventions).

To see more detailed properties supported by the service, check the auto-generated configuration documentation for the version of the service that you are using.


What's Next

Layouts API

Layouts Service Configuration


Suggested Edits are limited on API Reference Pages

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