Awesome
vue-golden-layout
DEPRECATED: The project is not maintained anymore. A new version for Vue3 has been begun here : https://github.com/emedware/v3-gl-ext
Integration of the golden-layout to Vue
Installation
npm i -S vue-golden-layout
Fast example
<golden-layout>
<gl-row>
<gl-component title="component1">
<h1>Component 1</h1>
</gl-component>
<gl-stack>
<gl-component title="component2">
<h1>Component 2</h1>
</gl-component>
<gl-component title="component3">
<h1>Component 3</h1>
</gl-component>
</gl-stack>
</gl-row>
</golden-layout>
Note: each component who is not rendered in a stack will indeed be rendered in a golden-layout singleton stack.
Bigger example
Demo available here
A more complex exemple is in the project when git-cloned. In order to test, the static sample application can be compiled like this:
npm install
npm run demo
You can now browse http://localhost:9000
The example can be found in the sources under the '/demo' folder
Usage
import vgl from 'vue-golden-layout'
Vue.use(vgl);
In case of incompatibility with bundlers, vue-golden-layout
can be bundeled by the sources.
The sources entry point is in vue-golden-layout/src/index.ts
import vgl from 'vue-golden-layout/src'
Vue.use(vgl);
Don't forget in order to make it work
- Include a golden-layout theme CSS.
import 'golden-layout/src/css/goldenlayout-light-theme.css'
Available themes are light
, dark
, soda
, translucent
.
goldenlayout-base.css
is already integrated to the library.
Structure
Elements like <gl-row>
, <gl-col>
and <gl-stack>
can be represented in a tree - they respectively stand for a golden-layout row, column and stack.
Components
Component are described by extension - namely, by giving their content using the data from the defining component.
<gl-component>
<h1>Heydoo</h1>
Price: {{priceLess}}
</gl-component>
Saving/restoring states
TL;DR: The state is the model of the golden-layout object
The golden-layout
has a property and an event named state
.
- The event is triggered when the state has changed (even deeply, like a deep watch).
- The property is used at mount to initialise the configuration. After that, any change will have no effect.
- The
state
property can be aPromise
, then the golden-layout will be rendered only when thePromise
has been resolved.
Notes:
- The property
state
can be given minified or not - The event
state
gives indeed the minified version of the config, and the expanded version as a second argument. - It is also the
v-model
of thegolden-layout
- In order to reload a state, the Vue object structure must corresp to the state it be applied to
- If there is a miss-match between the Vue object structure and the state, the
golden-layout
objectcreation-error
event will be raised
- If there is a miss-match between the Vue object structure and the state, the
Sub-object states
Every <gl-... >
can have a :state.sync
property (Dictionary
) that will be saved along his other properties in the golden-layout state.
This is a good place for example for custom containers to store locally what is needed to be persisted.
Components events and properties
Events
Layout' events
Straight forwards from golden-layout, refer to their doc
itemCreated
stackCreated
rowCreated
tabCreated
columnCreated
componentCreated
selectionChanged
windowOpened
windowClosed
itemDestroyed
initialised
activeContentItemChanged
Contained objects' events
Straight forwards from golden-layout, refer to their doc
stateChanged
titleChanged
activeContentItemChanged
beforeItemDestroyed
itemDestroyed
itemCreated
Components' events
Straight forwards from golden-layout, refer to their doc
open
destroy
close
tab
hide
show
resize
Properties
Layout' properties
@Prop({default: true}) hasHeaders: boolean
@Prop({default: true}) reorderEnabled: boolean
@Prop({default: false}) selectionEnabled: boolean
@Prop({default: true}) popoutWholeStack: boolean
@Prop({default: true}) closePopoutsOnUnload: boolean
@Prop({default: true}) showPopoutIcon: boolean
@Prop({default: true}) showMaximiseIcon: boolean
@Prop({default: true}) showCloseIcon: boolean
@Prop({default: 5}) borderWidth: number
@Prop({default: 10}) minItemHeight: number
@Prop({default: 10}) minItemWidth: number
@Prop({default: 20}) headerHeight: number
@Prop({default: 300}) dragProxyWidth: number
@Prop({default: 200}) dragProxyHeight: number
popup-timeout
(default: 5 = 5 seconds)
When the state change, an event is fired and provides the new state. Unfortunately, when something is poped-out, querying the state will raise an exception if the pop-out' golden-layout is not loaded. Hence, the first call to GoldenLayout.toConfig()
will for sure raise an exception.
The policy chosen here is to then wait a bit and try again. In order to avoid infinite exception+try-again, a time-out is still specified.
Therefore:
- Changing this value to higher will not postpone the event fireing, it will just allow more time for the pop-out to load before raising an exception
- This can be useful to increase in applications where the main page has some long loading process before displaying the golden-layout
Contained objects' properties
title: string
: Used for tab titletabId: string
: Used as thev-model
of agl-stack
orgl-dstack
to determine/set the active tabwidth: number
height: number
closable: boolean
reorderEnabled: boolean
hidden: boolean
Contained objects' methods
show()
andhide()
respectively show and hide the elementfocus()
brings the element in front recursively, making sure all tabs are right for them to be visible (also brings the window in front if needed)delete()
delete the vue-object and the gl-objectnodePath
is the unique path to this node from the golden-layout root (can change). The golden-layout object has a methodgetSubChild(path: string)
that returns this vue-object (useful between page reload)
Containers
Containers have an additional color-group: boolean
property defaulted to false
.
A container for which this property is set to true
will see all his descendants have a color assigned to their tabs.
This is meant to be used when the same component can be used twice on different objects, to follow in the pop-outs which is the descendant of which.
Note: by default, routes that are glCustomContainer
have a color-group
set to true
Specific components
Some components have been programmed as an extension, even if they are not part of golden-layout proprio sensu.
gl-dstack
Duplicatable stacks are stacks that should always remain in the main window as their content is modified programatically. These stacks, when poped-out, remain in the main screen while their content is poped-out.
Components defined in it that are not closable
nor reorder-enabled
will stay in the stack in the main window.
gl-router
The router is a glContainer
that aims to sublimate the <router-view />
It lets users manage their routes in tabs, open them in a split screen or even popped-out in another browser window on another physical display.
The main usage is <gl-router />
. Any options of router-view
still has to be implemented.
Note: gl-router
is a gl-dstack
.
gl-router' slots
A default content to render all routes can be provided as the route
slot template - with or without scope : if a scope is queried, it will be the route object.
If this content is provided, it should contain a <main />
tag that will be filled with the loaded route component.
Note: the provided template will be ignored when maximised/popped-out.
All the components in the default slot will be added as tabs in the router.
gl-router' properties
titler
Allows to specify a function that takes a route object in parameter and gives the string that will be used as tab title.
If none is specified, the default is to take $route.meta.title
- this means that routes have to be defined with a title in their meta-data.
empty-route
Specify the URL to use when the user closes all the tabs ("/"
by default)
gl-route
gl-route
s are components displaying a route. They are meant to be used in a gl-router but only have to be used in a golden-layout container.
They can take a name
and/or a path
, and their closable
and reorder-enabled
properties are false by default. They can be forced a title
but their container' titler
will be used if not.
Note: all the elements inside them will have a this.$route
pointing to the given route, not the actual URL.
glCustomContainers
Users can define components who describe a part of the layout. In order to do this, instead of extending Vue
, the component has to extend glCustomContainer
.
var comp = Vue.extend({...});
// becomes
var vgl = require('vue-golden-layout')
var comp = vgl.glCustomContainer.extend({...});
@Component
export class MyComp extends Vue {
...
}
// becomes
import { glCustomContainer } from 'vue-golden-layout'
@Component
export class MyComp extends glCustomContainer {
...
}
The template' root must therefore be a proper golden-layout child (row, col, stack, ...)
These components can be used as route components.
Low-level functionalities
Global components
Some golden-layout global component can be given before any instanciation (while declaring classes) by calling this function:
import { registerGlobalComponent } from 'vue-golden-layout'
// registerGlobalComponent(name: string, comp: (gl: goldenLayout, container: any, state: any)=> void)
(container: any, state: any)=> void
is the signature of a gloden-layout component and they are created per golden-layout instances
isSubWindow
import { isSubWindow } from 'vue-golden-layout'
The main application component will be created in any pop-out that is opened. The <golden-layout>
node will generate an empty HTML content, so nothing in it will be rendered. Though, if needed, this value is true
when the component is generated in a pop-out which indicate that the component won't even be rendered and should take no action.
CSS
The elements with the glComponent
CSS class are the ones directly included in the <div>
controlled and sized by golden-layout and answers to this class to fit in the layout child container, that can be overridden
.glComponent {
width: 100%;
height: 100%;
overflow: auto;
}
Objects linking
Golden-layout and Vue both have objects representing their internal state. A glRow
is associated with a ContentItem
.
Each vue object has a glObject
property and, vice versa, each golden-layout object has a vueObject
property linking to each another.
Virtual vs actual tree
Vue objects (rows, components, stacks, ...) all have a $parent
that retrieve their Vue' parent. Also their children might be retrieved with $children
.
Though, the user might change the order of things and who contain what. To retrieve the golden-layout-wise hierarchy, we can use glParent
as well as glChildren
on the vue objects to retrieve vue objects.