Skip to content

Latest commit

 

History

History
350 lines (239 loc) · 11.6 KB

README.md

File metadata and controls

350 lines (239 loc) · 11.6 KB
Raw

vue-golden-layout

npm Not Maintained

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 a Promise, then the golden-layout will be rendered only when the Promise 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 the golden-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 object creation-error event will be raised

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 title
  • tabId: string: Used as the v-model of a gl-stack or gl-dstack to determine/set the active tab
  • width: number
  • height: number
  • closable: boolean
  • reorderEnabled: boolean
  • hidden: boolean

Contained objects' methods

  • show() and hide() respectively show and hide the element
  • focus() 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-object
  • nodePath is the unique path to this node from the golden-layout root (can change). The golden-layout object has a method getSubChild(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-routes 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.