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 4 ways Golden Layout can bind to a component:

  1. Embedding via Registration (classic)
    A component’s constructor/factory is registered with Golden Layout. Golden Layout will instantiate an instance when required. The constructor/factory will add the component’s root HTML element within Golden Layout’s own DOM hierarchy sub-tree. This is the classic Golden Layout binding method. With this binding method an ancestor of the component’s root HTML element could be reparented if the layout changes.
  2. Embedding via Events
    Components are obtained on demand by events. An event handler will construct or otherwise fetch the component and return it. The event handler will also add the component’s root HTML element within Golden Layout’s own DOM hierarchy sub-tree. This is the binding method introduced in version 2.
  3. Virtual via Registration
    A component’s constructor/factory is registered with Golden Layout. Golden Layout will instantiate an instance when required. The component will use the same positioning as virtual components however Golden Layout will handle all the events internally.
  4. Virtual via Events (Virtual Components)
    With virtual components, Golden Layout never interacts directly with components. The application controls the construction/allocation, destruction/deallocation and positioning of components. Golden Layout will advise the application when components are needed and no longer needed via events. It will also advise about components’ positioning via events. This allows an application to control the placement of components in the DOM hierarchy and components’ root HTML element’s ancestors are not reparented when the layout is changed.

Embedding via Registration

Registering a component and specifying static positioning is the classic GoldenLayout approach to binding components. The components are registered with GoldenLayout and specify a constructor or callback function used to create a component whenever a new instance is needed in the layout. When the constructor or callback is invoked, it is passed a container object which includes a HTML element. The constructor or callback will create the object and make its top level HTML element a child of the container’s HTML element. The component is then part of the Golden Layout’s DOM hierarchy. Whenever the layout is re-arranged, the GoldenLayout DOM is adjusted to reflect the new layout hierarchy. Effectively this involves the ancestors of components’ root HTML elements being reparented when a layout is changed.

The following functions can be used to register components.

Embedding via Events

To give applications more control over the allocation of components, you can bind components with events instead of registration. If a handler is assigned to the event VirtualLayout.bindComponentEvent it will be fired whenever a new component is needed. The handler should:

When a component is removed from Golden Layout it will be necessary to remove the component’s top level HTML elements as children of container.element. Other component ‘tear-down’ actions may also be required. These actions can be carried out in either the VirtualLayout.unbindComponentEvent event or the component container’s beforeComponentRelease event (or both). Both these events will be fired (if handlers are assigned) when a component is no longer needed in Golden Layout.

Virtual via Events

With virtual components, Golden Layout knows nothing about components and does not include the component’s HTML elements in its own DOM hierarchy. Instead, whenever a component needs its position, size or visibility changed, Golden Layout will fire events which allow the application to change a component’s position, size or visibility. This is analogous to virtual grids where strings and other content to be displayed in a grid, are not included within the grid. Instead the grid fires events whenever it needs to display content. The application will return the required content.

Virtual Components has the following advantages:

With Virtual Components the following events need to be handled:

The apitest application demonstrates how virtual components are implemented.

When using virtual components, think of Golden Layout as more of an engine calculating position rather than actually positioning components. This binding method requires more work to set up than other binding methods. However it offers more flexibility and opens up more design opportunities. For example with virtual components, any HTML element could be the parent for your components (not just the Golden Layout container). You can even have different parents for different components. This allows, for example, some of your components have one parent, and the others a different parent. They could then inherit different CSS or handle event propagation differently.

Virtual via Registration

These events give applications a lot of flexibility with positioning components in Golden Layout - but at the expense of more effort of integrating into Golden Layout. It is however, possible to get the same benefits of Virtual Components with just registering a component. In this case, a component will be registered as in classic approach to Golden Layout binding, however, within Golden Layout, the component will be handled like a virtual component. Golden Layout will internally handle the necessary events.

Existing applications using register functions in Golden Layout can easily be updated to use virtual binding by:

  1. The register functions have a new parameter virtual. By default, this is false, specifying the classic binding in Golden Layout. Set this to true to specify that components of that type should be implemented internally as virtual components.
  2. Components need to have a getter: rootHtmlElement which returns the component’s root HTML element. Components written in TypeScript should implement the GoldenLayout.VirtuableComponent interface.
  3. Components’ rootHtmlElement element need to have its overflow CSS property set to hidden.
  4. Ensure that the Golden Layout container HTML element is positioned (ie. its position property is not static).

With these changes, applications can continue to use Golden Layout as they are now however Golden Layout will internally use virtual component binding.

Please note there will be a couple of minor behaviour changes:

Also note that ‘virtual via registration’ binding is not supported by the GoldenLayout.registerGetComponentConstructorCallback() registration function.

Multiple binding methods

An application can use multiple methods of binding components for different component types. Whenever a component needs to be bound, Golden Layout will try to bind in the following order:

  1. First check if its type has been registered. If so, it will bind using that registration.
  2. Check whether there is a bindComponentEvent handler. If so, this event will be used to bind it as a virtual component.
  3. Check whether there is a getComponentEvent handler. If so, this event will be used to bind the component statically within the Golden Layout DOM. This method is deprecated.
  4. If none of the above, then an exception will be raised.

If you use both ‘Virtual via Events’ and ‘Embedding via Events’, then the unbindComponentEvent handler can use the ComponentContainer.virtual field to determine which of these binding methods was used for a component.

VirtualLayout class

The inheritance hierarchy for the Golden Layout class is: LayoutManager -> VirtualLayout -> GoldenLayout.

The VirtualLayout class implements all the Golden Layout functionality except for the register functions. If you only intend to use virtual components using the bindComponentEvent, you can create an instance of VirtualLayout instead of GoldenLayout.

Usage Scenarios