This version is a substantial change from the previous (1.5.9) version. The change can be summarised as:
Before migrating from version 1, it is important to review the following:
As part of the port, the code base was significantly refactored. A number of features have been dropped from the version 1.0 as their implementation was not robust enough to meet the reliability requirements of version 2. The dropped features are:
publicAPIs are generally available to applications.
Version 2 has been re-written in TypeScript. A general code cleanup has been carried out as part of this re-write.
Also, some changes have been made to the GoldenLayout API. Where possible, backwards compatibility has been retained,however functions and properties kept for backwards compatibility have been marked as deprecated. It is strongly recommend applications be migrated to the new API.
Configs are now strongly typed. In addition, GoldenLayout now has “Configs” and “Resolved Configs”
LayoutConfig.saveLayout()which returns a “Resolved Config”.
For persistence of configs, always save the “Resolved Config” returned by
LayoutManager.saveLayout(). When reloading a saved Layout, first convert the saved “Resolved Config” to a “Config” by calling
Both “Resolved Config” and “Config” have 2 types of interface hierarchies:
ItemConfig.id property now has type
string (instead of its previous
string | string type). For backwards compatibility, when
ItemConfig.id is resolved, it will still accept an
id with of type string array. This will allow handling of legacy saved configs in which
id contains an array of strings (including possibly the legacy maximise indicator). When such an
id is resolved, the array is first checked for the legacy maximise indicator and then the first element becomes the
id string value. The remaining elements are discarded.
ComponentItemConfig.componentName property has now been replaced by property
componentType is of type
JsonValue. While a component type can now be specified by values that can be serialised by JSON,
componentType must be of type
string if it is registered with one of the following functions:
LayoutConfig has a
root property which specifies the ItemConfig of root content item of the layout.
root is not optional and must always be specified.
selectionEnabled property has been removed. Clicking of Stack Headers can now be handled with the new
stackHeaderClick event (which is always enabled).
ResolvedLayoutConfig now has functions to minify and unminify configurations:
For examples of how to create LayoutConfigs, please refer to the
apitest program in the repository.
Many of the Config properties have been deprecated as they overlapped or were moved to more appropriate locations. Please refer to the
config.ts source file for more information about these deprecations.
GoldenLayout is now a distinct class which is a descendant of the
VirtualLayout class, which in turn is a descendant of the
LayoutManager class. Your application should always create an instance of either
VirtualLayout constructors takes 3 optionals parameters:
Note that the initial Layout is no longer specified in this constructor. Instead it is loaded with
LayoutManager.loadLayout() (see below).
The GoldenLayout class now handles component registration. LayoutManager no longer includes any component registration functions. The following changes to registration functions have been made:
registerComponent()however only used when registering a component constructor.
LayoutManager.registerComponent()however only used when registering a call back function (closure) for creating components.
registerComponent(). Use the new
LayoutConfigparameter. This can also be subsequently called whenever the GoldenLayout layout is to be replaced.
LayoutConfig. Replaces the existing
unminifyConfig()functions. Use the respective functions in
updateSize(). Use the new
rootItem(new property) Specifies the root content item of the layout (not the Ground content item).
root. This has been replaced with the internal property
groundItem. You probably want to use the new
focusComponent()will focus the specified component item. Only one component item can have focus. If previously, another component item had focus, then it will lose focus (become blurred).
blurevents will be emitted as appropriate unless the
suppressEventparameter is set to true.
clearComponentFocus()which removes any existing component item focus. If focus is removed, a
blurevent will be emitted unless the
suppressEventparameter is set to true.
getComponentEventNow implemented in the VirtualLayout class but has been deprecated. Use
AbstractContentItemhas been renamed to
configproperty has been removed. Use the toConfig() method instead (as recommended in the original GoldenLayout documentation).
configproperties such as
typeare now available as properties of
ContentItemor its descendants (where appropriate).
idnow has type
string. (It used to be
string | string.)
ItemContainerhas been renamed to
Componenthas been renamed to
ComponentItem. “Component” now refers to the external component hosted inside GoldenLayout
Roothas been renamed to
GroundItemand has been marked as internal only. Applications should never access GroundItem. Note that the layout’s root ContentItem is GroundItem’s only child. You can access this root ContentItem with
Stack.setActiveContentItem()have been renamed to respective
ContentItem.deselect()have been removed. Use the new
ComponentItem.focus()(new function) will focus the specified ComponentItem. It will also remove focus from another component item which previously had focus. Only one component item can have focus at any time. If layout focus has changed, a
focusevent will be emitted (unless suppressEvent parameter is set to true).
ComponentItem.blur()(new function) will remove focus from the specified ComponentItem. After this is called, no component item in the layout will have focus. If the component lost focus, a
blurevent will be emitted (unless suppressEvent parameter is set to true).
element(new property - replaces
getElement(). Use the new
ComponentItemConfigused to create the contained component.
stateRequestEventis fired whenever GoldenLayout wants the latest state for a component. Calling
LayoutManager.saveLayout()will cause this event to be fired (if it is defined). If it is not defined, then the initial state in the ItemConfig or the latest state set in
setState()will be saved.
beforeComponentRelease(new EventEmitter event)
beforeComponentReleaseis emitted on the container before a component is released. Components can use this event to dispose of resources.
getState()unless you are using the deprecated
ComponentContainer.initialStategetter if you have migrated to the new
setState()has been marked as deprecated. If possible, use the new
replaceComponent()allows you to replace a component in a container without otherwise affecting the layout.
Several properties and functions have been renamed in
tab.ts. Please search for “@deprecated” in these files for these changes.
undefinedis used instead of
nullfor new properties, events etc. Some internals have also been switched to use
null. Existing properties using
nullmostly have been left as is however it is possible that some of these internal changes have affected external properties/events/methods.
For most changes, the existing functions and properties have been left in place but marked as deprecated. It is strongly recommended that applications be reworked not to use these deprecations. Bugs associated with deprecations will be given low priority (or not fixed at all). Also, deprecated aliases, methods and properties may be removed in future releases.
All API elements (classes, interfaces, functions etc) have been labelled as either
internal. Applications should only use
public API elements. Internal API elements are subject to change and no consideration will be given to backwards compatibility when these are changed.
The library distribution includes 2 TypeScript declaration (typing) files:
index.d.tswhich contains only public API elements. Applications should use this declaration file to access the library.
golden-layout-untrimmed.d.tswhich contains all (public and internal) API elements. Use this declaration file if you wish to access any API element in the library however please take the above warning into account.
Note that the allocation of API elements to either public or internal has not been finalised. However any element used in either the
apitest application or the example Angular application will remain labelled as public.