golden-layout

NPM version License

Golden Layout is a Javascript layout manager which enables you to layout components in a web page and re-arrange them with drag and drop.

Important Note: This is the main Golden Layout website. Another Golden Layout website is https://golden-layout.com. This other website describes Version 1 of Golden Layout. The information at https://golden-layout.com may be useful to gain an initial understanding of Golden Layout however please note that it is now out of date.

Table of Contents

Features

Installation / Usage

Library

Golden Layout is shipped via NPM. Use the following commands to install it into an application package:
npm i golden-layout

Source

The source can be installed by cloning the repository at:
https://github.com/golden-layout/golden-layout

To build the distribution locally, open a shell at the golden-layout directory/folder and run the following commands:

  1. npm install or npm ci (recommended) to install required dependencies
  2. npm run build to generate the distribution (dist subfolder). This script will:
    • delete the existing lib and dist folders
    • compile the TypeScript code
    • generate the rolled up TypeScript definition files (index.d.ts and golden-layout-untrimmed.d.ts)
    • generate source map
    • copy the style files to the dist folder

Note that the lib subfolder only holds the TypeScript declaration files generated by the compiler. Generally this subfolder can be ignored. It is used during the build process to generate the rolled up TypeScript definition files.

Build and run demo/test app

After installing the source and building the distribution, you can build and start the apitest (demo) app to view the library in action. Use the following commands:

Building single-file bundles

We provide different types of single file bundles for easier consumption without toolchain in-place. To do this, run npm run build:bundles, afterwards find your bundled files in dist/bundle/. Bundles are not built by default and are not included in the NPM package, we recommend everyone to consume the library through NPM and webpack.

Debugging Golden Layout library

The apitest app can be used to debug the Golden Layout library. Its webpack configuration will import the Golden Layout library source map, allowing debuggers to step through the library source code and place break points.

If you wish to test the library with other applications, you can link to the Golden Layout repository without having to install it into the application from NPM. This is done with the npm link command. Use the following steps:

  1. Run the npm link from a shell in the golden-layout source repository top level folder.
  2. Run npm link golden-layout from a shell in your application’s top level folder.

Your application will then use the distribution in the Golden Layout repository dist subfolder. If you wish to make changes to the Golden Layout library, you will need to run the build:api to regenerate the dist folder.

Run npm install to remove the npm link.

Learn

The following information sources are available which can be used to learn how to use Golden Layout:

Description

Structure

The structure of a Golden Layout object consists of its LayoutManager object and ContentItem objects which define the layout itself. See Structure for more details.

Binding Components

Golden Layout binds to components and then controls their position, size and visibility (positioning) so that they fit within a layout. There are several different ways in which Golden Layout can bind to components. The easiest method is to register a component type and then specify that component type in a component’s configuration.

See Binding Components for a full description of how Golden Layout component binding works.

Frameworks

Golden Layout has been designed to work with JavaScript application frameworks such as Angular and Vue. Typically these types of frameworks wrap HTML elements with their own components. Instead of an application being a tree of HTML elements, it is a tree of framework components, each of which wrap an HTML element.

To support these frameworks, Golden Layout implements ‘Virtual Components’. This allows framework components to be embedded within Golden Layout without having to use advanced framework techniques to allow the relevant framework component HTML elements to be displayed in a layout.

See Frameworks for a description and examples covering how to use Golden Layout with JavaScript application frameworks.

Sizing components

Within a layout structure, it is necessary to specify the size of RowOrColumn content items and their children. More.

Layout resizing

A layout should normally resize to always fit within Golden Layout’s container element. This resizing can be configured to occur automatically or can be manually managed. More

Component Focus

Components can have focus. This is analagous to HTML elements having focus. Only one component can have focus at any time. More

Location Selectors

LocationSelectors specify the location of a component in terms of a parent and a index. They can be used when adding components programatically. More

Popouts

A component in a layout can be ‘popped’ out into a separate browser window. It can be then be viewed separately from the main layout. More

Migration from previous versions

Upgrading to Version 2

With version 2, Golden Layout was ported to TypeScript. Substantial changes to its feature set and API were made as part of this conversion. These changes are summarised here.

This site is open source. Improve this page.