DOCSEARCHbyAlgolia
Submit Docs

Golden Layout

repository·master·Indexed 27 days ago

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

A multi-screen JavaScript layout manager (version 2.6.0) that enables the creation of complex, draggable, and resizable component layouts. It supports native popups, touch interaction, and integration with frameworks like Angular and Vue. The library provides multiple component binding methods, including classic registration, event-based embedding, and virtual components for maximum design flexibility and DOM control.

Tokens
19.6K
Snippets
16
Records
119
Agent score
88%

What's inside golden-layout

  1. Understand Golden Layout component binding methods

    master

    Golden Layout supports four distinct ways to bind components, which determine how the library manages their lifecycle, DOM positioning, and visibility:

    1. Embedding via Registration (Classic): You register a constructor or factory. Golden Layout instantiates the component and manages its DOM placement. Note that component ancestors may be reparented during layout changes.
    2. Embedding via Events: Components are fetched on demand via event handlers. This provides more control over allocation while still allowing Golden Layout to manage the DOM hierarchy.
    3. Virtual via Registration: A component's constructor is registered, but it uses virtual positioning logic. Golden Layout handles events internally.
    4. Virtual via Events (Virtual Components): The application has full control over construction, destruction, and DOM placement. Golden Layout only advises the application via events when components are needed, no longer needed, or when their position changes. This prevents component ancestors from being reparented during layout changes.

  2. Understand the Golden Layout object structure

    master

    A Golden Layout instance (GoldenLayout or VirtualLayout) is a descendant of a LayoutManager. The structure consists of two primary parts:

    1. Main Layout: A tree of ContentItems (excluding popouts). The root of this tree can be a ComponentItem, a Stack, or a RowOrColumn.
    2. BrowserPopouts: A list of open popout windows that appear above the main layout.

    Lifecycle Note:

    • The LayoutManager and its internal GroundItem are permanent and exist for the life of the manager.
    • ComponentItem, RowOrColumn, Stack, and BrowserPopout objects are transient; they are created when a layout is loaded/modified and destroyed when a layout is closed or replaced.

  3. Manage Layout Configurations (Config vs Resolved Config)

    master

    Golden Layout distinguishes between Config and Resolved Config to handle optionality and defaults.

    • Config: Used by application developers. It supports optional properties and handles backwards compatibility by migrating deprecated properties to new values.
    • Resolved Config: Used internally by Golden Layout. It is a fully populated configuration where all optional values have been replaced by their defaults.

    Persistence Workflow

    To persist and reload layouts correctly:

    1. Saving: Always save the Resolved Config returned by LayoutManager.saveLayout().
    2. Loading: When reloading a saved layout, convert the Resolved Config back to a Config using LayoutConfig.fromResolved() before passing it to loadLayout().

    Configuration Minification

    Instead of using LayoutManager methods, use the functions available on the ResolvedLayoutConfig object:

    • minifyConfig()
    • unminifyConfig()

  4. Use Golden Layout with other frameworks

    master

    To use Golden Layout with frameworks other than Angular or Vue, follow these steps:

    1. Implement the Virtual via events component binding.
    2. Set up the required handlers as described in the component binding guides.
    3. Once handlers are configured, you can use standard LayoutManager functions to manage your layout, such as:
      • LayoutManager.loadLayout()
      • LayoutManager.addComponent()

  5. Build and run the apitest demo app

    master

    After building the distribution from source, you can run the apitest demo application to see the library in action.

    • To build only: npm run apitest:build
    • To build and start the development server: npm run apitest:serve

    Once running, the app is available at http://localhost:3000/.

    npm run apitest:serve

  6. Use LocationSelectors to specify component placement

    master

    A LocationSelector defines where a new ContentItem should be placed by specifying how to search for a parent and the preferred child index.

    When using LayoutManager.addComponentAtLocation() or LayoutManager.newComponentAtLocation(), you provide an array of LocationSelector objects. The manager attempts to find a valid location by iterating through the array in order. The first selector that successfully identifies a valid parent is used. If no selectors in the array result in a valid location, the component will not be added.

    Note that some typeId values are guaranteed to succeed (like LocationSelector.TypeId.Root), while others (like LocationSelector.TypeId.FirstStack) may fail if the layout is empty or doesn't match the criteria.

    // Example of the LocationSelector interface structure
export interface LocationSelector {
    typeId: LocationSelector.TypeId;
    index?: number;
}

  7. Manage component state in Version 2

    master

    Version 2 introduces a new way to handle component state. The setState() method is deprecated.

    Instead of manually managing state via getState() and setState(), you should use the stateRequestEvent on the ComponentContainer. When LayoutManager.saveLayout() is called, this event is fired, allowing the component to provide its latest state. If you need to access the initial state used during creation, use the initialState getter.

  8. Embed components via Events

    master

    To gain more control over component allocation, you can use event-based binding instead of registration.

    Implementation Steps:

    1. Assign a handler to the VirtualLayout.bindComponentEvent.
    2. When the event fires, the handler must:
      • Create or fetch the component.
      • Ensure the component's top-level HTML element is made a child of container.element.
      • Return the component wrapped in a BindableComponent interface with virtual: false.

    Cleanup: When a component is removed, you must manually remove its top-level HTML elements from container.element. You can perform teardown in either:

    • The VirtualLayout.unbindComponentEvent event.
    • The component container's beforeComponentRelease event.

  9. Install Golden Layout via npm

    master

    You can install Golden Layout as an NPM module. Note that the NPM modules are currently not updated frequently, so building from source is the recommended approach for the latest features.

    To install the existing NPM package, run: npm i golden-layout

    npm i golden-layout

  11. Integrate Golden Layout with Frameworks using Virtual via events binding

    master

    When using modern frameworks (like Angular or Vue) that manage a tree of components rather than raw HTML elements, the recommended approach for integrating Golden Layout is using Virtual via events component binding. This method prevents Golden Layout from interfering with the framework's component tree.

    For frameworks not explicitly covered by dedicated guides, you should use the Virtual via events binding and set up the necessary handlers to allow Golden Layout to interact with your framework's component lifecycle.

  12. Identify Public vs Internal APIs

    master

    Golden Layout distinguishes between public and internal API elements.

    • Public APIs: These are stable and intended for application use. They are found in the index.d.ts TypeScript declaration file.
    • Internal APIs: These are subject to change without notice and may break backwards compatibility. They are found in golden-layout-untrimmed.d.ts.

    Always use the public API elements for your applications to ensure stability.