Golden Layout

https://golden-layout.github.io/golden-layout/
Admin
Golden Layout is a JavaScript layout manager that enables you to layout components in a web page and...
Tokens:8,939
Snippets:117
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Build and Test Commands

Source: https://golden-layout.github.io/golden-layout

Commands for installing dependencies, building the distribution, and running the demo application.

```bash
npm install
```

```bash
npm ci
```

```bash
npm run build
```

```bash
npm run apitest:build
```

```bash
npm run apitest:serve
```

```bash
npm run build:bundles
```

```bash
npm link
```

```bash
npm link golden-layout
```

--------------------------------

### Install Golden Layout via NPM

Source: https://golden-layout.github.io/golden-layout

Use this command to add the library to an existing application package.

```bash
npm i golden-layout
```

--------------------------------

### Clone Golden Layout Repository

Source: https://golden-layout.github.io/golden-layout

Use this URL to clone the source code repository.

```bash
https://github.com/golden-layout/golden-layout
```

--------------------------------

### Import Golden Layout Modules

Source: https://golden-layout.github.io/golden-layout

Import the necessary classes when using EcmaScript modules.

```javascript
import { GoldenLayout, LayoutConfig, ResolvedLayoutConfig, ItemConfig, ComponentItemConfig, ResolvedItemConfig, RowOrColumn, Tab } from './golden-layout.js';
```

--------------------------------

### LayoutManager Methods for Adding Components

Source: https://golden-layout.github.io/golden-layout/location-selectors

Explains how LayoutManager methods utilize LocationSelectors to add components to the layout.

```APIDOC
## LayoutManager Methods for Adding Components

### Description
The `LayoutManager.addComponentAtLocation()` and `LayoutManager.newComponentAtLocation()` methods use an array of `LocationSelectors` to determine the placement of a new or added component. These functions iterate through the `LocationSelectors` array, attempting to find a valid location. If a valid location is found, it's used for the component. If no valid location is found after checking all selectors, the component is not added.

The `LayoutManager.addComponent()` and `LayoutManager.newComponent()` methods use a default `LocationSelectors` array that is guaranteed to find a location because its last element is `LocationSelector.TypeId.Root`. Therefore, these methods will always succeed in adding a component.

### Available Location Selector Arrays
- **`LayoutManager.defaultLocationSelectors`**: The default array used by `addComponent` and `newComponent`.
- **`LayoutManager.afterFocusedItemIfPossibleLocationSelectors`**: An alternative predefined array.
```

--------------------------------

### Listen for userBroadcast events

Source: https://golden-layout.github.io/golden-layout/popouts

Use the EventHub to listen for broadcasted messages from other windows.

```typescript
layoutManager.eventHub.on('userBroadcast',  (...ev: EventEmitter.UnknownParams) => {
  // respond to user broadcast event
});
```

--------------------------------

### Handling Virtual Component Events

Source: https://golden-layout.github.io/golden-layout/binding-components

This section details the specific events that need to be handled when using virtual components in Golden Layout.

```APIDOC
## Virtual Component Events

### `VirtualLayout.bindComponentEvent`

**Description:** Fired when Golden Layout needs to bind to a new virtual component. The handler receives the `container` and the resolved `itemConfig`.

**Handler Responsibilities:**
*   Create or fetch the component using `itemConfig`.
*   Obtain the component's top-level HTML element.
*   Ensure the element has `position: absolute`.
*   Append the element to Golden Layout's root HTML element.
*   Store the component in a map using the `container` as the key.
*   Add handlers for `virtualRectingRequiredEvent` and `virtualVisibilityChangeRequiredEvent`.
*   Return an object conforming to the `BindableComponent` interface with `virtual: true`.

**Example:**
```typescript
private handleBindComponentEvent(container: ComponentContainer, itemConfig: ResolvedComponentItemConfig) {
    const componentTypeName = ResolvedComponentItemConfig.resolveComponentTypeName(itemConfig);
    if (componentTypeName === undefined) {
        throw new Error('handleBindComponentEvent: Undefined componentTypeName');
    }
    const component = this.createVirtualComponent(container, componentTypeName, itemConfig.componentState);
    const componentRootElement = component.rootHtmlElement;
    this._layoutElement.appendChild(componentRootElement);
    this._boundComponentMap.set(container, component);
    container.virtualRectingRequiredEvent = (container, width, height) => this.handleContainerVirtualRectingRequiredEvent(container, width, height);
    container.virtualVisibilityChangeRequiredEvent = (container, visible) => this.handleContainerVisibilityChangeRequiredEvent(container, visible);
    return {
        component,
        virtual: true,
    };
}
```

### `VirtualLayout.unbindComponentEvent`

**Description:** Fired when a component is removed from Golden Layout. The handler receives the `container`.

**Handler Responsibilities:**
*   Retrieve the component from the map using the `container`.
*   Remove the component's root HTML element from Golden Layout's root element.
*   Remove the component from the map.

**Example:**
```typescript
private handleUnbindComponentEvent(container: ComponentContainer) {
    const component = this._boundComponentMap.get(container);
    if (component === undefined) {
        throw new Error('handleUnbindComponentEvent: Component not found');
    }

    const componentRootElement = component.rootHtmlElement;
    if (componentRootElement === undefined) {
        throw new Error('handleUnbindComponentEvent: Component does not have a root HTML element');
    }

    this._layoutElement.removeChild(componentRootElement);
    this._boundComponentMap.delete(container);
}
```

### `LayoutManager.beforeVirtualRectingEvent`

**Description:** This event is fired whenever one or more components need to be repositioned as a result of a layout change. It does not require explicit handling but can be used for optimization, such as caching the position of Golden Layout's root HTML element using `getBoundingClientRect()`.
```

--------------------------------

### Handle Bind Component Event

Source: https://golden-layout.github.io/golden-layout/binding-components

Implementation for the bindComponentEvent handler to initialize and register a virtual component within the layout.

```typescript
  private handleBindComponentEvent(container: ComponentContainer, itemConfig: ResolvedComponentItemConfig) {
      // Use ResolvedComponentItemConfig.resolveComponentTypeNamecan to resolve component types to a unique name
      const componentTypeName = ResolvedComponentItemConfig.resolveComponentTypeName(itemConfig);
      if (componentTypeName === undefined) {
          throw new Error('handleBindComponentEvent: Undefined componentTypeName');
      }
      const component = this.createVirtualComponent(container, componentTypeName, itemConfig.componentState);
      const componentRootElement = component.rootHtmlElement;
      this._layoutElement.appendChild(componentRootElement);
      this._boundComponentMap.set(container, component);
      container.virtualRectingRequiredEvent = (container, width, height) => this.handleContainerVirtualRectingRequiredEvent(container, width, height);
      container.virtualVisibilityChangeRequiredEvent = (container, visible) => this.handleContainerVisibilityChangeRequiredEvent(container, visible);
      return {
          component,
          virtual: true,
      };
  }
```

--------------------------------

### Vue Component Usage with Golden Layout

Source: https://golden-layout.github.io/golden-layout/frameworks/vue/embedding-via-events.html

This Vue component demonstrates how to use the `useGoldenLayout` composable. It sets up a layout with two 'Test' components and uses teleportation to render them. Ensure Golden Layout CSS is imported.

```html
<template>
  <div ref="element" style="width: 100%; height: 75vh">
    <teleport
      v-for="{ id, type, element } in componentInstances"
      :key="id"
      :to="element"
    >
      <component :is="type"></component>
    </teleport>
  </div>
</template>
```

```javascript
<script lang="ts">
import { useGoldenLayout } from "@/use-golden-layout";
import { defineComponent, h, shallowRef } from "vue";
import "golden-layout/dist/css/goldenlayout-base.css";
import "golden-layout/dist/css/themes/goldenlayout-dark-theme.css";

const Test = defineComponent({ render: () => h('span', 'It works!') });

const components = { Test, /* other components */ };

export default defineComponent({
  components,
  setup() {
    interface ComponentInstance {
      id: number;
      type: string;
      element: HTMLElement;
    }
    let instanceId = 0;
    const componentTypes = new Set(Object.keys(components));
    const componentInstances = shallowRef<ComponentInstance[]>([]);

    const createComponent = (type: string, element: HTMLElement) => {
      if (!componentTypes.has(type)) {
        throw new Error(`Component not found: '${type}'`);
      }
      ++instanceId;
      componentInstances.value = componentInstances.value.concat({
        id: instanceId,
        type,
        element,
      });
    };
    const destroyComponent = (toBeRemoved: HTMLElement) => {
      componentInstances.value = componentInstances.value.filter(
        ({ element }) => element !== toBeRemoved
      );
    };

    const { element } = useGoldenLayout(createComponent, destroyComponent, {
      root: {
        type: "column",
        content: [
          {
            type: "component",
            componentType: "Test",
          },
          {
            type: "component",
            componentType: "Test",
          },
        ],
      },
    });

    return { element, componentInstances };
  },
});
</script>

```

--------------------------------

### Vue Composable Hook for Golden Layout

Source: https://golden-layout.github.io/golden-layout/frameworks/vue/embedding-via-events.html

This composable hook, `useGoldenLayout`, facilitates the integration of Golden Layout into Vue applications. It requires functions to create and destroy components and optionally accepts a layout configuration. Ensure the document is ready before initializing the layout.

```typescript
import { GoldenLayout, LayoutConfig } from 'golden-layout';
import { onMounted, ref, shallowRef } from 'vue';

export const isClient = typeof window !== 'undefined';
export const isDocumentReady = () => isClient && document.readyState === 'complete' && document.body != null;

export function useDocumentReady(func: () => void) {
    onMounted(() => {
        console.log(isDocumentReady());
        if (isDocumentReady()) func();
        else
            document.addEventListener('readystatechange', () => isDocumentReady() && func(), {
                passive: true,
            });
    });
}

export function useGoldenLayout(
    createComponent: (type: string, container: HTMLElement) => ComponentContainer.Component,
    destroyComponent: (container: HTMLElement) => void,
    config?: LayoutConfig
) {
    const element = shallowRef<HTMLElement | null>(null);
    const layout = shallowRef<GoldenLayout | null>(null);
    const initialized = ref(false);

    useDocumentReady(() => {
        if (element.value == null) throw new Error('Element must be set.');
        const goldenLayout = new GoldenLayout(element.value);

        goldenLayout.bindComponentEvent = (container, itemConfig) => {
            const { componentType } = itemConfig;
            if (typeof componentType !== 'string') throw new Error('Invalid component type.');
            const component = createComponent(componentType, container.element);
            return {
                component,
                virtual: false,
            }
        }
        goldenLayout.unbindComponentEvent = container => {
            destroyComponent(container.element);
        }

        if (config != null) goldenLayout.loadLayout(config);

        // https://github.com/microsoft/TypeScript/issues/34933
        layout.value = goldenLayout as any;

        initialized.value = true;
    });

    return { element, initialized, layout };
}

```

--------------------------------

### LocationSelector Interface

Source: https://golden-layout.github.io/golden-layout/location-selectors

Defines the structure of a LocationSelector, used to determine where a component should be placed within the layout.

```APIDOC
## LocationSelector Interface

### Description
LocationSelectors specify the location of a component in terms of a parent and an index. They are useful for specifying where a new ContentItem should be placed. A `LocationSelector` does not specify the parent directly, but rather how the parent is to be searched for.

### Type Definition
```typescript
export interface LocationSelector {
    typeId: LocationSelector.TypeId;
    index?: number;
}
```

### Fields
- **typeId** (LocationSelector.TypeId) - Required - Specifies the algorithm used to search for a parent.
- **index** (number) - Optional - Used by the algorithm to determine the preferred child position under the parent.
```

--------------------------------

### Virtual Components Overview

Source: https://golden-layout.github.io/golden-layout/binding-components

Virtual components in Golden Layout allow the layout manager to control component positioning, sizing, and visibility without directly managing their DOM elements. Instead, Golden Layout fires events that the application must handle to update the components.

```APIDOC
## Virtual Components

Golden Layout can operate in a 'virtual' mode where it does not manage the DOM of the components directly. Instead, it fires events when component properties like position, size, or visibility need to change. The application is responsible for handling these events and updating the components accordingly.

**Advantages of Virtual Components:**
*   **Preserves Component Hierarchy:** Avoids issues with iframes, sockets, or framework-specific component lifecycles by not reparenting DOM elements.
*   **Simplified Integration:** Easier to integrate with frameworks like Angular and Vue without breaking their component structures.
*   **Easier Debugging:** Results in a shallower DOM hierarchy, simplifying debugging.
```

--------------------------------

### ComponentContainer.virtualRectingRequiredEvent

Source: https://golden-layout.github.io/golden-layout/binding-components

Fired when a component’s position and/or size need to be changed. The handler is responsible for calculating the relative position and updating the component's CSS properties.

```APIDOC
## EVENT ComponentContainer.virtualRectingRequiredEvent

### Description
Fired when a component’s position and/or size need to be changed. The handler is passed the container and the component’s required width and height.

### Parameters
- **container** (ComponentContainer) - Required - The container instance.
- **width** (number) - Required - The required width.
- **height** (number) - Required - The required height.
```

--------------------------------

### Handle Component Recting Event in Golden Layout

Source: https://golden-layout.github.io/golden-layout/binding-components

Implement this handler for `ComponentContainer.virtualRectingRequiredEvent`. It calculates and applies the component's position and dimensions relative to the Golden Layout root element. Ensure the component has a root HTML element.

```typescript
  private handleContainerVirtualRectingRequiredEvent(container: ComponentContainer, width: number, height: number) {
      const component = this._boundComponentMap.get(container);
      if (component === undefined) {
          throw new Error('handleContainerVirtualRectingRequiredEvent: Component not found');
      }

      const rootElement = component.rootHtmlElement;
      if (rootElement === undefined) {
          throw new Error('handleContainerVirtualRectingRequiredEvent: Component does not have a root HTML element');
      }

      const containerBoundingClientRect = container.element.getBoundingClientRect();
      const left = containerBoundingClientRect.left - this._goldenLayoutBoundingClientRect.left;
      rootElement.style.left = this.numberToPixels(left);
      const top = containerBoundingClientRect.top - this._goldenLayoutBoundingClientRect.top;
      rootElement.style.top = this.numberToPixels(top);
      rootElement.style.width = this.numberToPixels(width);
      rootElement.style.height = this.numberToPixels(height);
  }
```

--------------------------------

### Define LocationSelector Interface

Source: https://golden-layout.github.io/golden-layout/location-selectors

This interface defines the structure for a LocationSelector, specifying the algorithm type and an optional index for placement.

```typescript
export interface LocationSelector {
    typeId: LocationSelector.TypeId;
    index?: number;
}

```

--------------------------------

### Handle Component Z-Index Change in Golden Layout

Source: https://golden-layout.github.io/golden-layout/binding-components

Implement this handler for `ComponentContainer.virtualZIndexChangeRequiredEvent`. It sets the component's z-index using the provided `defaultZIndex`. Ensure the component has a root HTML element.

```typescript
  private handleContainerVirtualZIndexChangeRequiredEvent(container: ComponentContainer, logicalZIndex: LogicalZIndex, defaultZIndex: string) {
      const component = this._boundComponentMap.get(container);
      if (component === undefined) {
          throw new Error('handleContainerVirtualZIndexChangeRequiredEvent: Component not found');
      }

      const componentRootElement = component.rootHtmlElement;
      if (componentRootElement === undefined) {
          throw new Error('handleContainerVirtualZIndexChangeRequiredEvent: Component does not have a root HTML element');
      }

      componentRootElement.style.zIndex = defaultZIndex;
  }
```

--------------------------------

### ComponentContainer.virtualZIndexChangeRequiredEvent

Source: https://golden-layout.github.io/golden-layout/binding-components

Fired when a component’s z-index needs to be changed. The handler updates the z-index of the component's top-level HTML element.

```APIDOC
## EVENT ComponentContainer.virtualZIndexChangeRequiredEvent

### Description
Fired when a component’s z-index needs to be changed. The handler is passed the container, a logical z-index, and the default style z-index.

### Parameters
- **container** (ComponentContainer) - Required - The container instance.
- **logicalZIndex** (LogicalZIndex) - Required - The logical z-index.
- **defaultZIndex** (string) - Required - The default style z-index.
```

--------------------------------

### Handle Unbind Component Event

Source: https://golden-layout.github.io/golden-layout/binding-components

Implementation for the unbindComponentEvent handler to clean up and remove a component from the layout.

```typescript
  private handleUnbindComponentEvent(container: ComponentContainer) {
      const component = this._boundComponentMap.get(container);
      if (component === undefined) {
          throw new Error('handleUnbindComponentEvent: Component not found');
      }

      const componentRootElement = component.rootHtmlElement;
      if (componentRootElement === undefined) {
          throw new Error('handleUnbindComponentEvent: Component does not have a root HTML element');
      }

      this._layoutElement.removeChild(componentRootElement);
      this._boundComponentMap.delete(container);
  }
```

--------------------------------

### Handle Component Visibility Change in Golden Layout

Source: https://golden-layout.github.io/golden-layout/binding-components

Implement this handler for `ComponentContainer.virtualVisibilityChangeRequiredEvent`. It toggles the component's visibility by setting the `display` style property. Ensure the component has a root HTML element.

```typescript
  private handleContainerVisibilityChangeRequiredEvent(container: ComponentContainer, visible: boolean) {
      const component = this._boundComponentMap.get(container);
      if (component === undefined) {
          throw new Error('handleContainerVisibilityChangeRequiredEvent: Component not found');
      }

      const componentRootElement = component.rootHtmlElement;
      if (componentRootElement === undefined) {
          throw new Error('handleContainerVisibilityChangeRequiredEvent: Component does not have a root HTML element');
      }

      if (visible) {
          componentRootElement.style.display = '';
      } else {
          componentRootElement.style.display = 'none';
      }
  }
```

--------------------------------

### ComponentContainer.virtualVisibilityChangeRequiredEvent

Source: https://golden-layout.github.io/golden-layout/binding-components

Fired when a component’s visibility needs to be changed. The handler updates the display property of the component's top-level HTML element.

```APIDOC
## EVENT ComponentContainer.virtualVisibilityChangeRequiredEvent

### Description
Fired when a component’s visibility needs to be changed. The handler is passed the container and a boolean specifying visibility.

### Parameters
- **container** (ComponentContainer) - Required - The container instance.
- **visible** (boolean) - Required - The visibility state.
```
Tokens:
Raw