AboutSupportDeveloper GuideVersion 40.128.82.13

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.

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.

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

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

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);
});

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

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);
  • tab-created
  • container-created
  • layout-state-changed
  • tab-closed
  • tab-dropped

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"
}

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"
}

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"
}

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.
}

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

Accessors

  • get me(): Identity
  • Returns Identity

    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

  • 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>

    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' });
  • Returns the configuration of the window's layout. Returns the same information that is returned for all windows in getSnapshot.

    Returns Promise<any>

    Cannot be called from a View.

    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();
  • Retrieves the attached views in current window layout.

    Returns Promise<View[]>

    const layout = fin.Platform.Layout.getCurrentSync();
    const views = await layout.getCurrentViews();
  • Retrieves the top level content item of the layout.

    Returns Promise<TabStack | ColumnOrRow>

    Cannot be called from a view.

    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)`);
  • Replaces a Platform window's layout with a new layout.

    Parameters

    Returns Promise<void>

    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.

    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);
  • 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>

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

    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);