AboutSupportDeveloper GuideVersion 40.130.101.1

Class Layout

Layouts give app providers the ability to embed multiple views in a single window. The Layout namespace enables the initialization and manipulation of a window's Layout. A Layout will emit events locally on the DOM element representing the layout-container.

Layout.DOMEvents

When a Layout is created, it emits events onto the DOM element representing the Layout container. This Layout container is the DOM element referenced by containerId in Layout.init. You can use the built-in event emitter to listen to these events using addEventListener. The events are emitted synchronously and only in the process where the Layout exists. Any values returned by the called listeners are ignored and will be discarded. If the target DOM element is destroyed, any events that have been set up on that element will be destroyed.

Remarks

The built-in event emitter is not an OpenFin event emitter so it doesn't share propagation semantics.

addEventListener(type, listener [, options]);

Adds a listener to the end of the listeners array for the specified event.

Example

const myLayoutContainer = document.getElementById('layout-container');

myLayoutContainer.addEventListener('tab-created', function(event) {
     const { tabSelector } = event.detail;
     const tabElement = document.getElementById(tabSelector);
     const existingColor = tabElement.style.backgroundColor;
     tabElement.style.backgroundColor = "red";
     setTimeout(() => {
         tabElement.style.backgroundColor = existingColor;
     }, 2000);
});

removeEventListener(type, listener [, options]);

Adds a listener to the end of the listeners array for the specified event.

Example

const myLayoutContainer = document.getElementById('layout-container');

const listener = function(event) {
    console.log(event.detail);
    console.log('container-created event fired once, removing listener');
    myLayoutContainer.removeEventListener('container-created', listener);
};

myLayoutContainer.addEventListener('container-created', listener);

Supported event types are:

  • tab-created
  • container-created
  • layout-state-changed
  • tab-closed
  • tab-dropped

Layout DOM Node Events

tab-created

Generated when a tab is created. As a user drags and drops tabs within window, new tabs are created. A single view may have multiple tabs created and destroyed during its lifetime attached to a single window.

// The response has the following shape in event.detail:
{
    containerSelector: "container-component_A",
    name: "component_A",
    tabSelector: "tab-component_A",
    topic: "openfin-DOM-event",
    type: "tab-created",
    uuid: "OpenFin POC"
}

container-created

Generated when a container is created. A single view will have only one container during its lifetime attached to a single window and the container's lifecycle is tied to the view. To discover when the container is destroyed, please listen to view-detached event.

// The response has the following shape in event.detail:
{
    containerSelector: "container-component_A",
    name: "component_A",
    tabSelector: "tab-component_A",
    topic: "openfin-DOM-event",
    type: "container-created",
    uuid: "OpenFin POC"
}

layout-state-changed

Generated when the state of the layout changes in any way, such as a view added/removed/replaced. Note that this event can fire frequently as the underlying layout can change multiple components from all kinds of changes (resizing for example). Given this, it is recommended to debounce this event and then you can use the Layout.getConfig API to retrieve the most up-to-date state.

// The response has the following shape in event.detail
{
    containerSelector: "container-component_A",
    name: "component_A",
    tabSelector: "tab-component_A",
    topic: "openfin-DOM-event",
    type: "layout-state-changed",
    uuid: "OpenFin POC"
}

tab-closed

Generated when a tab is closed.

// The response has the following shape in event.detail:
{
    containerSelector: "container-component_A",
    name: "component_A",
    tabSelector: "tab-component_A",
    topic: "openfin-DOM-event",
    type: "tab-closed",
    uuid: "OpenFin POC",
    url: "http://openfin.co"   // The url of the view that was closed.
}

tab-dropped

Generated when a tab is dropped.

// The response has the following shape in event.detail:
{
    containerSelector: "container-component_A",
    name: "component_A",
    tabSelector: "tab-component_A",
    topic: "openfin-DOM-event",
    type: "tab-dropped",
    uuid: "OpenFin POC",
    url: "http://openfin.co"    // The url of the view linked to the dropped tab.
}

Hierarchy

  • Base
    • Layout

Properties

identity

Accessors

me

Methods

addView applyPreset closeView getConfig getCurrentViews getRootItem getStackByViewIdentity replace replaceView

Properties

identity

identity: Identity | LayoutIdentity

Accessors

me

  • get me(): Identity

  • Returns Identity

    Deprecated

    me should only be accessed from the fin global (FinApi.me); access through entity classes is not guaranteed to behave sensibly in all calling contexts.

Methods

addView

  • addView(viewOptions, options?): Promise<{
        identity: Identity;
    }>

  • Adds a view to the platform layout. Behaves like @link{Platform#createView} with the current layout as the target.

    Parameters

    • viewOptions: Partial<ViewOptions>

      The options for creating the view.

    • options: {
          location?: {
              id: string;
              index?: number;
          };
          targetView?: Identity;
      } = {}

      Optional parameters for adding the view.

      • Optionallocation?: {
            id: string;
            index?: number;
        }

        The location where the view should be added.

        • id: string
        • Optionalindex?: number
      • OptionaltargetView?: Identity

        The target view to which the new view should be added.

    Returns Promise<{
        identity: Identity;
    }>

    A promise that resolves to an object containing the identity of the added view.

applyPreset

  • applyPreset(options): Promise<void>

  • Replaces a Platform window's layout with a preset layout arrangement using the existing Views attached to the window. The preset options are columns, grid, rows, and tabs.

    Parameters

    • options: PresetLayoutOptions

      Mandatory object with presetType property that sets which preset layout arrangement to use. The preset options are columns, grid, rows, and tabs.

    Returns Promise<void>

    Example

    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 layout = fin.Platform.Layout.wrapSync(windowIdentity);
    await layout.applyPreset({ presetType: 'grid' });

    // wait 5 seconds until you change the layout from grid to tabs
    await new Promise (res => setTimeout(res, 5000));
    await layout.applyPreset({ presetType: 'tabs' });

closeView

  • closeView(viewIdentity): Promise<void>

  • Closes a view by its identity. Throws an error if the view does not belong to the current layout. Behaves like @link{Platform#closeView} but only closes the view if it belongs the current layout.

    Parameters

    • viewIdentity: Identity

      The identity of the view to close.

    Returns Promise<void>

    A promise that resolves when the view is closed.

getConfig

  • getConfig(): Promise<any>

  • Returns the configuration of the window's layout. Returns the same information that is returned for all windows in getSnapshot.

    Returns Promise<any>

    Remarks

    Cannot be called from a View.

    Example

    const layout = fin.Platform.Layout.getCurrentSync();
    // Use wrapped instance to get the layout configuration of the current window's Layout:
    const layoutConfig = await layout.getConfig();

getCurrentViews

  • getCurrentViews(): Promise<View[]>

  • Retrieves the attached views in current window layout.

    Returns Promise<View[]>

    Example

    const layout = fin.Platform.Layout.getCurrentSync();
    const views = await layout.getCurrentViews();

getRootItem

  • getRootItem(): Promise<TabStack | ColumnOrRow>

  • Retrieves the top level content item of the layout.

    Returns Promise<TabStack | ColumnOrRow>

    Remarks

    Cannot be called from a view.

    Example

    if (!fin.me.isWindow) {
        throw new Error('Not running in a platform View.');
    }

    // From the layout window
    const layout = fin.Platform.Layout.getCurrentSync();
    // Retrieves the ColumnOrRow instance
    const rootItem = await layout.getRootItem();
    const content = await rootItem.getContent();
    console.log(`The root ColumnOrRow instance has ${content.length} item(s)`);

getStackByViewIdentity

  • getStackByViewIdentity(identity): Promise<TabStack>

  • Retrieves the OpenFin.TabStack instance which the View belongs to.

    Parameters

    Returns Promise<TabStack>

    Example

    const viewIdentity = { uuid: 'uuid', name: 'view-name' };
    const stack = await fin.View.wrapSync(viewIdentity).getStackByViewIdentity(viewIdentity);
    console.log(await stack.getViews());

replace

  • replace(layout): Promise<void>

  • Replaces a Platform window's layout with a new layout.

    Parameters

    Returns Promise<void>

    Remarks

    Any views that were in the old layout but not the new layout will be destroyed. Views will be assigned a randomly generated name to avoid collisions.

    Example

    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 layout = fin.Platform.Layout.wrapSync(windowIdentity);

    const newLayout = {
        content: [
            {
                type: 'stack',
                content: [
                    {
                        type: 'component',
                        componentName: 'view',
                        componentState: {
                            name: 'new_component_A1',
                            processAffinity: 'ps_1',
                            url: 'https://www.example.com'
                        }
                    },
                    {
                        type: 'component',
                        componentName: 'view',
                        componentState: {
                            name: 'new_component_A2',
                            url: 'https://cdn.openfin.co/embed-web/chart.html'
                        }
                    }
                ]
            }
        ]
    };

    layout.replace(newLayout);

replaceView

  • replaceView(viewToReplace, newView): Promise<void>

  • Replaces the specified view with a view with the provided configuration.

    Parameters

    • viewToReplace: Identity

      Identity of the view to be replaced

    • newView: Partial<ViewOptions>

      Creation options of the new view.

    Returns Promise<void>

    Remarks

    The old view is stripped of its listeners and either closed or attached to the provider window depending on detachOnClose view option.

    Example

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

    const layout = fin.Platform.Layout.wrapSync(currentWindow.identity);
    const viewToReplace = (await currentWindow.getCurrentViews())[0];
    const newViewConfig = {url: 'https://example.com'};
    await layout.replaceView(viewToReplace.identity, newViewConfig);

Settings

On This Page

Layout.DOMEventsSupported event types are:Layout DOM Node Eventslayout-state-changed
Properties
Accessors
Methods