gridstack-profile
Version:
TypeScript/JS lib for dashboard layout and creation, responsive, mobile support, no external dependencies, with many wrappers (React, Angular, Vue, Ember, knockout...)
1,091 lines • 101 kB
JavaScript
/*!
* GridStack 8.2.1-dev
* https://gridstackjs.com/
*
* Copyright (c) 2021-2022 Alain Dumesny
* see root license https://github.com/gridstack/gridstack.js/tree/master/LICENSE
*/
import { GridStackEngine } from './gridstack-engine';
import { Utils, obsolete } from './utils';
import { gridDefaults, dragInDefaultOptions } from './types';
/*
* and include D&D by default
* TODO: while we could generate a gridstack-static.js at smaller size - saves about 31k (41k -> 72k)
* I don't know how to generate the DD only code at the remaining 31k to delay load as code depends on Gridstack.ts
* also it caused loading issues in prod - see https://github.com/gridstack/gridstack.js/issues/2039
*/
import { DDGridStack } from './dd-gridstack';
import { isTouch } from './dd-touch';
import { DDManager } from './dd-manager';
/** global instance */
const dd = new DDGridStack;
// export all dependent file as well to make it easier for users to just import the main file
export * from './types';
export * from './utils';
export * from './gridstack-engine';
export * from './dd-gridstack';
/**
* Main gridstack class - you will need to call `GridStack.init()` first to initialize your grid.
* Note: your grid elements MUST have the following classes for the CSS layout to work:
* @example
* <div class="grid-stack">
* <div class="grid-stack-item">
* <div class="grid-stack-item-content">Item 1</div>
* </div>
* </div>
*/
class GridStack {
/**
* initializing the HTML element, or selector string, into a grid will return the grid. Calling it again will
* simply return the existing instance (ignore any passed options). There is also an initAll() version that support
* multiple grids initialization at once. Or you can use addGrid() to create the entire grid from JSON.
* @param options grid options (optional)
* @param elOrString element or CSS selector (first one used) to convert to a grid (default to '.grid-stack' class selector)
*
* @example
* let grid = GridStack.init();
*
* Note: the HTMLElement (of type GridHTMLElement) will store a `gridstack: GridStack` value that can be retrieve later
* let grid = document.querySelector('.grid-stack').gridstack;
*/
static init(options = {}, elOrString = '.grid-stack') {
let el = GridStack.getGridElement(elOrString);
if (!el) {
if (typeof elOrString === 'string') {
console.error('GridStack.initAll() no grid was found with selector "' + elOrString + '" - element missing or wrong selector ?' +
'\nNote: ".grid-stack" is required for proper CSS styling and drag/drop, and is the default selector.');
}
else {
console.error('GridStack.init() no grid element was passed.');
}
return null;
}
if (!el.gridstack) {
el.gridstack = new GridStack(el, Utils.cloneDeep(options));
}
return el.gridstack;
}
/**
* Will initialize a list of elements (given a selector) and return an array of grids.
* @param options grid options (optional)
* @param selector elements selector to convert to grids (default to '.grid-stack' class selector)
*
* @example
* let grids = GridStack.initAll();
* grids.forEach(...)
*/
static initAll(options = {}, selector = '.grid-stack') {
let grids = [];
GridStack.getGridElements(selector).forEach(el => {
if (!el.gridstack) {
el.gridstack = new GridStack(el, Utils.cloneDeep(options));
}
grids.push(el.gridstack);
});
if (grids.length === 0) {
console.error('GridStack.initAll() no grid was found with selector "' + selector + '" - element missing or wrong selector ?' +
'\nNote: ".grid-stack" is required for proper CSS styling and drag/drop, and is the default selector.');
}
return grids;
}
/**
* call to create a grid with the given options, including loading any children from JSON structure. This will call GridStack.init(), then
* grid.load() on any passed children (recursively). Great alternative to calling init() if you want entire grid to come from
* JSON serialized data, including options.
* @param parent HTML element parent to the grid
* @param opt grids options used to initialize the grid, and list of children
*/
static addGrid(parent, opt = {}) {
if (!parent)
return null;
let el = parent;
if (el.gridstack) {
// already a grid - set option and load data
const grid = el.gridstack;
if (opt)
grid.opts = { ...grid.opts, ...opt };
if (opt.children !== undefined)
grid.load(opt.children);
return grid;
}
// create the grid element, but check if the passed 'parent' already has grid styling and should be used instead
const parentIsGrid = parent.classList.contains('grid-stack');
if (!parentIsGrid || GridStack.addRemoveCB) {
if (GridStack.addRemoveCB) {
el = GridStack.addRemoveCB(parent, opt, true, true);
}
else {
let doc = document.implementation.createHTMLDocument(''); // IE needs a param
doc.body.innerHTML = `<div class="grid-stack ${opt.class || ''}"></div>`;
el = doc.body.children[0];
parent.appendChild(el);
}
}
// create grid class and load any children
let grid = GridStack.init(opt, el);
return grid;
}
/** call this method to register your engine instead of the default one.
* See instead `GridStackOptions.engineClass` if you only need to
* replace just one instance.
*/
static registerEngine(engineClass) {
GridStack.engineClass = engineClass;
}
/** @internal create placeholder DIV as needed */
get placeholder() {
if (!this._placeholder) {
let placeholderChild = document.createElement('div'); // child so padding match item-content
placeholderChild.className = 'placeholder-content';
if (this.opts.placeholderText) {
placeholderChild.innerHTML = this.opts.placeholderText;
}
this._placeholder = document.createElement('div');
this._placeholder.classList.add(this.opts.placeholderClass, gridDefaults.itemClass, this.opts.itemClass);
this.placeholder.appendChild(placeholderChild);
}
return this._placeholder;
}
/**
* Construct a grid item from the given element and options
* @param el
* @param opts
*/
constructor(el, opts = {}) {
/** @internal */
this._gsEventHandler = {};
/** @internal extra row added when dragging at the bottom of the grid */
this._extraDragRow = 0;
this.el = el; // exposed HTML element to the user
opts = opts || {}; // handles null/undefined/0
if (!el.classList.contains('grid-stack')) {
this.el.classList.add('grid-stack');
}
// if row property exists, replace minRow and maxRow instead
if (opts.row) {
opts.minRow = opts.maxRow = opts.row;
delete opts.row;
}
let rowAttr = Utils.toNumber(el.getAttribute('gs-row'));
// flag only valid in sub-grids (handled by parent, not here)
if (opts.column === 'auto') {
delete opts.column;
}
// save original setting so we can restore on save
if (opts.alwaysShowResizeHandle !== undefined) {
opts._alwaysShowResizeHandle = opts.alwaysShowResizeHandle;
}
// elements DOM attributes override any passed options (like CSS style) - merge the two together
let defaults = { ...Utils.cloneDeep(gridDefaults),
column: Utils.toNumber(el.getAttribute('gs-column')) || gridDefaults.column,
minRow: rowAttr ? rowAttr : Utils.toNumber(el.getAttribute('gs-min-row')) || gridDefaults.minRow,
maxRow: rowAttr ? rowAttr : Utils.toNumber(el.getAttribute('gs-max-row')) || gridDefaults.maxRow,
staticGrid: Utils.toBool(el.getAttribute('gs-static')) || gridDefaults.staticGrid,
draggable: {
handle: (opts.handleClass ? '.' + opts.handleClass : (opts.handle ? opts.handle : '')) || gridDefaults.draggable.handle,
},
removableOptions: {
accept: opts.itemClass ? '.' + opts.itemClass : gridDefaults.removableOptions.accept,
},
};
if (el.getAttribute('gs-animate')) { // default to true, but if set to false use that instead
defaults.animate = Utils.toBool(el.getAttribute('gs-animate'));
}
this.opts = Utils.defaults(opts, defaults);
opts = null; // make sure we use this.opts instead
this._initMargin(); // part of settings defaults...
// Now check if we're loading into 1 column mode FIRST so we don't do un-necessary work (like cellHeight = width / 12 then go 1 column)
if (this.opts.column !== 1 && !this.opts.disableOneColumnMode && this._widthOrContainer() <= this.opts.oneColumnSize) {
this._prevColumn = this.getColumn();
this.opts.column = 1;
}
if (this.opts.rtl === 'auto') {
this.opts.rtl = (el.style.direction === 'rtl');
}
if (this.opts.rtl) {
this.el.classList.add('grid-stack-rtl');
}
// check if we're been nested, and if so update our style and keep pointer around (used during save)
let parentGridItem = Utils.closestUpByClass(this.el, gridDefaults.itemClass)?.gridstackNode;
if (parentGridItem) {
parentGridItem.subGrid = this;
this.parentGridItem = parentGridItem;
this.el.classList.add('grid-stack-nested');
parentGridItem.el.classList.add('grid-stack-sub-grid');
}
this._isAutoCellHeight = (this.opts.cellHeight === 'auto');
if (this._isAutoCellHeight || this.opts.cellHeight === 'initial') {
// make the cell content square initially (will use resize/column event to keep it square)
this.cellHeight(undefined, false);
}
else {
// append unit if any are set
if (typeof this.opts.cellHeight == 'number' && this.opts.cellHeightUnit && this.opts.cellHeightUnit !== gridDefaults.cellHeightUnit) {
this.opts.cellHeight = this.opts.cellHeight + this.opts.cellHeightUnit;
delete this.opts.cellHeightUnit;
}
this.cellHeight(this.opts.cellHeight, false);
}
// see if we need to adjust auto-hide
if (this.opts.alwaysShowResizeHandle === 'mobile') {
this.opts.alwaysShowResizeHandle = isTouch;
}
this._styleSheetClass = 'gs-id-' + GridStackEngine._idSeq++;
this.el.classList.add(this._styleSheetClass);
this._setStaticClass();
let engineClass = this.opts.engineClass || GridStack.engineClass || GridStackEngine;
this.engine = new engineClass({
column: this.getColumn(),
float: this.opts.float,
maxRow: this.opts.maxRow,
onChange: (cbNodes) => {
let maxH = 0;
this.engine.nodes.forEach(n => { maxH = Math.max(maxH, n.y + n.h); });
cbNodes.forEach(n => {
let el = n.el;
if (!el)
return;
if (n._removeDOM) {
if (el)
el.remove();
delete n._removeDOM;
}
else {
this._writePosAttr(el, n);
}
});
this._updateStyles(false, maxH); // false = don't recreate, just append if need be
}
});
if (this.opts.auto) {
this.batchUpdate(); // prevent in between re-layout #1535 TODO: this only set float=true, need to prevent collision check...
this.getGridItems().forEach(el => this._prepareElement(el));
this.batchUpdate(false);
}
// load any passed in children as well, which overrides any DOM layout done above
if (this.opts.children) {
let children = this.opts.children;
delete this.opts.children;
if (children.length)
this.load(children); // don't load empty
}
this.setAnimation(this.opts.animate);
this._updateStyles();
this.el.classList.add('gs-' + this.opts.column);
// dynamic grids require pausing during drag to detect over to nest vs push
if (this.opts.subGridDynamic && !DDManager.pauseDrag)
DDManager.pauseDrag = true;
if (this.opts.draggable?.pause !== undefined)
DDManager.pauseDrag = this.opts.draggable.pause;
this._setupRemoveDrop();
this._setupAcceptWidget();
this._updateWindowResizeEvent();
}
/**
* add a new widget and returns it.
*
* Widget will be always placed even if result height is more than actual grid height.
* You need to use `willItFit()` before calling addWidget for additional check.
* See also `makeWidget()`.
*
* @example
* let grid = GridStack.init();
* grid.addWidget({w: 3, content: 'hello'});
* grid.addWidget('<div class="grid-stack-item"><div class="grid-stack-item-content">hello</div></div>', {w: 3});
*
* @param el GridStackWidget (which can have content string as well), html element, or string definition to add
* @param options widget position/size options (optional, and ignore if first param is already option) - see GridStackWidget
*/
addWidget(els, options) {
function isGridStackWidget(w) {
return w.el !== undefined || w.x !== undefined || w.y !== undefined || w.w !== undefined || w.h !== undefined || w.content !== undefined ? true : false;
}
let el;
let node;
if (typeof els === 'string') {
let doc = document.implementation.createHTMLDocument(''); // IE needs a param
doc.body.innerHTML = els;
el = doc.body.children[0];
}
else if (arguments.length === 0 || arguments.length === 1 && isGridStackWidget(els)) {
node = options = els;
if (node?.el) {
el = node.el; // re-use element stored in the node
}
else if (GridStack.addRemoveCB) {
el = GridStack.addRemoveCB(this.el, options, true, false);
}
else {
let content = options?.content || '';
let doc = document.implementation.createHTMLDocument(''); // IE needs a param
doc.body.innerHTML = `<div class="grid-stack-item ${this.opts.itemClass || ''}"><div class="grid-stack-item-content">${content}</div></div>`;
el = doc.body.children[0];
}
}
else {
el = els;
}
if (!el)
return;
// if the caller ended up initializing the widget in addRemoveCB, or we stared with one already, skip the rest
node = el.gridstackNode;
if (node && el.parentElement === this.el && this.engine.nodes.find(n => n._id === node._id))
return el;
// Tempting to initialize the passed in opt with default and valid values, but this break knockout demos
// as the actual value are filled in when _prepareElement() calls el.getAttribute('gs-xyz') before adding the node.
// So make sure we load any DOM attributes that are not specified in passed in options (which override)
let domAttr = this._readAttr(el);
options = Utils.cloneDeep(options) || {}; // make a copy before we modify in case caller re-uses it
Utils.defaults(options, domAttr);
node = this.engine.prepareNode(options);
this._writeAttr(el, options);
if (this._insertNotAppend) {
this.el.prepend(el);
}
else {
this.el.appendChild(el);
}
this.makeWidget(el, options);
return el;
}
/**
* Convert an existing gridItem element into a sub-grid with the given (optional) options, else inherit them
* from the parent's subGrid options.
* @param el gridItem element to convert
* @param ops (optional) sub-grid options, else default to node, then parent settings, else defaults
* @param nodeToAdd (optional) node to add to the newly created sub grid (used when dragging over existing regular item)
* @returns newly created grid
*/
makeSubGrid(el, ops, nodeToAdd, saveContent = true) {
let node = el.gridstackNode;
if (!node) {
node = this.makeWidget(el).gridstackNode;
}
if (node.subGrid?.el)
return node.subGrid; // already done
// find the template subGrid stored on a parent as fallback...
let subGridTemplate; // eslint-disable-next-line @typescript-eslint/no-this-alias
let grid = this;
while (grid && !subGridTemplate) {
subGridTemplate = grid.opts?.subGridOpts;
grid = grid.parentGridItem?.grid;
}
//... and set the create options
ops = Utils.cloneDeep({ ...(subGridTemplate || {}), children: undefined, ...(ops || node.subGridOpts) });
node.subGridOpts = ops;
// if column special case it set, remember that flag and set default
let autoColumn;
if (ops.column === 'auto') {
autoColumn = true;
ops.column = Math.max(node.w || 1, nodeToAdd?.w || 1);
ops.disableOneColumnMode = true; // driven by parent
}
// if we're converting an existing full item, move over the content to be the first sub item in the new grid
let content = node.el.querySelector('.grid-stack-item-content');
let newItem;
let newItemOpt;
if (saveContent) {
this._removeDD(node.el); // remove D&D since it's set on content div
newItemOpt = { ...node, x: 0, y: 0 };
Utils.removeInternalForSave(newItemOpt);
delete newItemOpt.subGridOpts;
if (node.content) {
newItemOpt.content = node.content;
delete node.content;
}
if (GridStack.addRemoveCB) {
newItem = GridStack.addRemoveCB(this.el, newItemOpt, true, false);
}
else {
let doc = document.implementation.createHTMLDocument(''); // IE needs a param
doc.body.innerHTML = `<div class="grid-stack-item"></div>`;
newItem = doc.body.children[0];
newItem.appendChild(content);
doc.body.innerHTML = `<div class="grid-stack-item-content"></div>`;
content = doc.body.children[0];
node.el.appendChild(content);
}
this._prepareDragDropByNode(node); // ... and restore original D&D
}
// if we're adding an additional item, make the container large enough to have them both
if (nodeToAdd) {
let w = autoColumn ? ops.column : node.w;
let h = node.h + nodeToAdd.h;
let style = node.el.style;
style.transition = 'none'; // show up instantly so we don't see scrollbar with nodeToAdd
this.update(node.el, { w, h });
setTimeout(() => style.transition = null); // recover animation
}
let subGrid = node.subGrid = GridStack.addGrid(content, ops);
if (nodeToAdd?._moving)
subGrid._isTemp = true; // prevent re-nesting as we add over
if (autoColumn)
subGrid._autoColumn = true;
// add the original content back as a child of hte newly created grid
if (saveContent) {
subGrid.addWidget(newItem, newItemOpt);
}
// now add any additional node
if (nodeToAdd) {
if (nodeToAdd._moving) {
// create an artificial event even for the just created grid to receive this item
window.setTimeout(() => Utils.simulateMouseEvent(nodeToAdd._event, 'mouseenter', subGrid.el), 0);
}
else {
subGrid.addWidget(node.el, node);
}
}
return subGrid;
}
/**
* called when an item was converted into a nested grid to accommodate a dragged over item, but then item leaves - return back
* to the original grid-item. Also called to remove empty sub-grids when last item is dragged out (since re-creating is simple)
*/
removeAsSubGrid(nodeThatRemoved) {
let pGrid = this.parentGridItem?.grid;
if (!pGrid)
return;
pGrid.batchUpdate();
pGrid.removeWidget(this.parentGridItem.el, true, true);
this.engine.nodes.forEach(n => {
// migrate any children over and offsetting by our location
n.x += this.parentGridItem.x;
n.y += this.parentGridItem.y;
pGrid.addWidget(n.el, n);
});
pGrid.batchUpdate(false);
if (this.parentGridItem)
delete this.parentGridItem.subGrid;
delete this.parentGridItem;
// create an artificial event for the original grid now that this one is gone (got a leave, but won't get enter)
if (nodeThatRemoved) {
window.setTimeout(() => Utils.simulateMouseEvent(nodeThatRemoved._event, 'mouseenter', pGrid.el), 0);
}
}
/**
* saves the current layout returning a list of widgets for serialization which might include any nested grids.
* @param saveContent if true (default) the latest html inside .grid-stack-content will be saved to GridStackWidget.content field, else it will
* be removed.
* @param saveGridOpt if true (default false), save the grid options itself, so you can call the new GridStack.addGrid()
* to recreate everything from scratch. GridStackOptions.children would then contain the widget list instead.
* @param saveCB callback for each node -> widget, so application can insert additional data to be saved into the widget data structure.
* @returns list of widgets or full grid option, including .children list of widgets
*/
save(saveContent = true, saveGridOpt = false, saveCB = GridStack.saveCB) {
// return copied GridStackWidget (with optionally .el) we can modify at will...
let list = this.engine.save(saveContent, saveCB);
// check for HTML content and nested grids
list.forEach(n => {
if (saveContent && n.el && !n.subGrid && !saveCB) { // sub-grid are saved differently, not plain content
let sub = n.el.querySelector('.grid-stack-item-content');
n.content = sub ? sub.innerHTML : undefined;
if (!n.content)
delete n.content;
}
else {
if (!saveContent && !saveCB) {
delete n.content;
}
// check for nested grid
if (n.subGrid?.el) {
const listOrOpt = n.subGrid.save(saveContent, saveGridOpt, saveCB);
n.subGridOpts = (saveGridOpt ? listOrOpt : { children: listOrOpt });
delete n.subGrid;
}
}
delete n.el;
});
// check if save entire grid options (needed for recursive) + children...
if (saveGridOpt) {
let o = Utils.cloneDeep(this.opts);
// delete default values that will be recreated on launch
if (o.marginBottom === o.marginTop && o.marginRight === o.marginLeft && o.marginTop === o.marginRight) {
o.margin = o.marginTop;
delete o.marginTop;
delete o.marginRight;
delete o.marginBottom;
delete o.marginLeft;
}
if (o.rtl === (this.el.style.direction === 'rtl')) {
o.rtl = 'auto';
}
if (this._isAutoCellHeight) {
o.cellHeight = 'auto';
}
if (this._autoColumn) {
o.column = 'auto';
delete o.disableOneColumnMode;
}
const origShow = o._alwaysShowResizeHandle;
delete o._alwaysShowResizeHandle;
if (origShow !== undefined) {
o.alwaysShowResizeHandle = origShow;
}
else {
delete o.alwaysShowResizeHandle;
}
Utils.removeInternalAndSame(o, gridDefaults);
o.children = list;
return o;
}
return list;
}
/**
* load the widgets from a list. This will call update() on each (matching by id) or add/remove widgets that are not there.
*
* @param layout list of widgets definition to update/create
* @param addAndRemove boolean (default true) or callback method can be passed to control if and how missing widgets can be added/removed, giving
* the user control of insertion.
*
* @example
* see http://gridstackjs.com/demo/serialization.html
**/
load(layout, addRemove = GridStack.addRemoveCB || true) {
let items = GridStack.Utils.sort([...layout], -1, this._prevColumn || this.getColumn()); // make copy before we mod/sort
this._insertNotAppend = true; // since create in reverse order...
// if we're loading a layout into for example 1 column (_prevColumn is set only when going to 1) and items don't fit, make sure to save
// the original wanted layout so we can scale back up correctly #1471
if (this._prevColumn && this._prevColumn !== this.opts.column && items.some(n => (n.x + n.w) > this.opts.column)) {
this._ignoreLayoutsNodeChange = true; // skip layout update
this.engine.cacheLayout(items, this._prevColumn, true);
}
// if given a different callback, temporally set it as global option so creating will use it
const prevCB = GridStack.addRemoveCB;
if (typeof (addRemove) === 'function')
GridStack.addRemoveCB = addRemove;
let removed = [];
this.batchUpdate();
// see if any items are missing from new layout and need to be removed first
if (addRemove) {
let copyNodes = [...this.engine.nodes]; // don't loop through array you modify
copyNodes.forEach(n => {
let item = items.find(w => n.id === w.id);
if (!item) {
if (GridStack.addRemoveCB)
GridStack.addRemoveCB(this.el, n, false, false);
removed.push(n); // batch keep track
this.removeWidget(n.el, true, false);
}
});
}
// now add/update the widgets
items.forEach(w => {
let item = (w.id !== undefined) ? this.engine.nodes.find(n => n.id === w.id) : undefined;
if (item) {
this.update(item.el, w);
if (w.subGridOpts?.children) { // update any sub grid as well
let sub = item.el.querySelector('.grid-stack');
if (sub && sub.gridstack) {
sub.gridstack.load(w.subGridOpts.children); // TODO: support updating grid options ?
this._insertNotAppend = true; // got reset by above call
}
}
}
else if (addRemove) {
this.addWidget(w);
}
});
this.engine.removedNodes = removed;
this.batchUpdate(false);
// after commit, clear that flag
delete this._ignoreLayoutsNodeChange;
delete this._insertNotAppend;
prevCB ? GridStack.addRemoveCB = prevCB : delete GridStack.addRemoveCB;
return this;
}
/**
* use before calling a bunch of `addWidget()` to prevent un-necessary relayouts in between (more efficient)
* and get a single event callback. You will see no changes until `batchUpdate(false)` is called.
*/
batchUpdate(flag = true) {
this.engine.batchUpdate(flag);
if (!flag) {
this._triggerRemoveEvent();
this._triggerAddEvent();
this._triggerChangeEvent();
}
return this;
}
/**
* Gets current cell height.
*/
getCellHeight(forcePixel = false) {
if (this.opts.cellHeight && this.opts.cellHeight !== 'auto' &&
(!forcePixel || !this.opts.cellHeightUnit || this.opts.cellHeightUnit === 'px')) {
return this.opts.cellHeight;
}
// else get first cell height
let el = this.el.querySelector('.' + this.opts.itemClass);
if (el) {
let height = Utils.toNumber(el.getAttribute('gs-h'));
return Math.round(el.offsetHeight / height);
}
// else do entire grid and # of rows (but doesn't work if min-height is the actual constrain)
let rows = parseInt(this.el.getAttribute('gs-current-row'));
return rows ? Math.round(this.el.getBoundingClientRect().height / rows) : this.opts.cellHeight;
}
/**
* Update current cell height - see `GridStackOptions.cellHeight` for format.
* This method rebuilds an internal CSS style sheet.
* Note: You can expect performance issues if call this method too often.
*
* @param val the cell height. If not passed (undefined), cells content will be made square (match width minus margin),
* if pass 0 the CSS will be generated by the application instead.
* @param update (Optional) if false, styles will not be updated
*
* @example
* grid.cellHeight(100); // same as 100px
* grid.cellHeight('70px');
* grid.cellHeight(grid.cellWidth() * 1.2);
*/
cellHeight(val, update = true) {
// if not called internally, check if we're changing mode
if (update && val !== undefined) {
if (this._isAutoCellHeight !== (val === 'auto')) {
this._isAutoCellHeight = (val === 'auto');
this._updateWindowResizeEvent();
}
}
if (val === 'initial' || val === 'auto') {
val = undefined;
}
// make item content be square
if (val === undefined) {
let marginDiff = -this.opts.marginRight - this.opts.marginLeft
+ this.opts.marginTop + this.opts.marginBottom;
val = this.cellWidth() + marginDiff;
}
let data = Utils.parseHeight(val);
if (this.opts.cellHeightUnit === data.unit && this.opts.cellHeight === data.h) {
return this;
}
this.opts.cellHeightUnit = data.unit;
this.opts.cellHeight = data.h;
if (update) {
this._updateStyles(true); // true = force re-create for current # of rows
}
return this;
}
/** Gets current cell width. */
cellWidth() {
return this._widthOrContainer() / this.getColumn();
}
/** return our expected width (or parent) for 1 column check */
_widthOrContainer() {
// use `offsetWidth` or `clientWidth` (no scrollbar) ?
// https://stackoverflow.com/questions/21064101/understanding-offsetwidth-clientwidth-scrollwidth-and-height-respectively
return (this.el.clientWidth || this.el.parentElement.clientWidth || window.innerWidth);
}
/** re-layout grid items to reclaim any empty space */
compact() {
this.engine.compact();
this._triggerChangeEvent();
return this;
}
/**
* set the number of columns in the grid. Will update existing widgets to conform to new number of columns,
* as well as cache the original layout so you can revert back to previous positions without loss.
* Requires `gridstack-extra.css` or `gridstack-extra.min.css` for [2-11],
* else you will need to generate correct CSS (see https://github.com/gridstack/gridstack.js#change-grid-columns)
* @param column - Integer > 0 (default 12).
* @param layout specify the type of re-layout that will happen (position, size, etc...).
* Note: items will never be outside of the current column boundaries. default (moveScale). Ignored for 1 column
*/
column(column, layout = 'moveScale') {
if (column < 1 || this.opts.column === column)
return this;
let oldColumn = this.getColumn();
// if we go into 1 column mode (which happens if we're sized less than minW unless disableOneColumnMode is on)
// then remember the original columns so we can restore.
if (column === 1) {
this._prevColumn = oldColumn;
}
else {
delete this._prevColumn;
}
this.el.classList.remove('gs-' + oldColumn);
this.el.classList.add('gs-' + column);
this.opts.column = this.engine.column = column;
// update the items now - see if the dom order nodes should be passed instead (else default to current list)
let domNodes;
if (column === 1 && this.opts.oneColumnModeDomSort) {
domNodes = [];
this.getGridItems().forEach(el => {
if (el.gridstackNode) {
domNodes.push(el.gridstackNode);
}
});
if (!domNodes.length) {
domNodes = undefined;
}
}
this.engine.updateNodeWidths(oldColumn, column, domNodes, layout);
if (this._isAutoCellHeight)
this.cellHeight();
// and trigger our event last...
this._ignoreLayoutsNodeChange = true; // skip layout update
this._triggerChangeEvent();
delete this._ignoreLayoutsNodeChange;
return this;
}
/**
* get the number of columns in the grid (default 12)
*/
getColumn() {
return this.opts.column;
}
/** returns an array of grid HTML elements (no placeholder) - used to iterate through our children in DOM order */
getGridItems() {
return Array.from(this.el.children)
.filter((el) => el.matches('.' + this.opts.itemClass) && !el.matches('.' + this.opts.placeholderClass));
}
/**
* Destroys a grid instance. DO NOT CALL any methods or access any vars after this as it will free up members.
* @param removeDOM if `false` grid and items HTML elements will not be removed from the DOM (Optional. Default `true`).
*/
destroy(removeDOM = true) {
if (!this.el)
return; // prevent multiple calls
this.offAll();
this._updateWindowResizeEvent(true);
this.setStatic(true, false); // permanently removes DD but don't set CSS class (we're going away)
this.setAnimation(false);
if (!removeDOM) {
this.removeAll(removeDOM);
this.el.classList.remove(this._styleSheetClass);
this.el.removeAttribute('gs-current-row');
}
else {
this.el.parentNode.removeChild(this.el);
}
this._removeStylesheet();
if (this.parentGridItem)
delete this.parentGridItem.subGrid;
delete this.parentGridItem;
delete this.opts;
delete this._placeholder;
delete this.engine;
delete this.el.gridstack; // remove circular dependency that would prevent a freeing
delete this.el;
return this;
}
/**
* enable/disable floating widgets (default: `false`) See [example](http://gridstackjs.com/demo/float.html)
*/
float(val) {
if (this.opts.float !== val) {
this.opts.float = this.engine.float = val;
this._triggerChangeEvent();
}
return this;
}
/**
* get the current float mode
*/
getFloat() {
return this.engine.float;
}
/**
* Get the position of the cell under a pixel on screen.
* @param position the position of the pixel to resolve in
* absolute coordinates, as an object with top and left properties
* @param useDocRelative if true, value will be based on document position vs parent position (Optional. Default false).
* Useful when grid is within `position: relative` element
*
* Returns an object with properties `x` and `y` i.e. the column and row in the grid.
*/
getCellFromPixel(position, useDocRelative = false) {
let box = this.el.getBoundingClientRect();
// console.log(`getBoundingClientRect left: ${box.left} top: ${box.top} w: ${box.w} h: ${box.h}`)
let containerPos;
if (useDocRelative) {
containerPos = { top: box.top + document.documentElement.scrollTop, left: box.left };
// console.log(`getCellFromPixel scrollTop: ${document.documentElement.scrollTop}`)
}
else {
containerPos = { top: this.el.offsetTop, left: this.el.offsetLeft };
// console.log(`getCellFromPixel offsetTop: ${containerPos.left} offsetLeft: ${containerPos.top}`)
}
let relativeLeft = position.left - containerPos.left;
let relativeTop = position.top - containerPos.top;
let columnWidth = (box.width / this.getColumn());
let rowHeight = (box.height / parseInt(this.el.getAttribute('gs-current-row')));
return { x: Math.floor(relativeLeft / columnWidth), y: Math.floor(relativeTop / rowHeight) };
}
/** returns the current number of rows, which will be at least `minRow` if set */
getRow() {
return Math.max(this.engine.getRow(), this.opts.minRow);
}
/**
* Checks if specified area is empty.
* @param x the position x.
* @param y the position y.
* @param w the width of to check
* @param h the height of to check
*/
isAreaEmpty(x, y, w, h) {
return this.engine.isAreaEmpty(x, y, w, h);
}
/**
* If you add elements to your grid by hand (or have some framework creating DOM), you have to tell gridstack afterwards to make them widgets.
* If you want gridstack to add the elements for you, use `addWidget()` instead.
* Makes the given element a widget and returns it.
* @param els widget or single selector to convert.
* @param options widget definition to use instead of reading attributes or using default sizing values
*
* @example
* let grid = GridStack.init();
* grid.el.appendChild('<div id="1" gs-w="3"></div>');
* grid.el.appendChild('<div id="2"></div>');
* grid.makeWidget('1');
* grid.makeWidget('2', {w:2, content: 'hello'});
*/
makeWidget(els, options) {
let el = GridStack.getElement(els);
this._prepareElement(el, true, options);
this._updateContainerHeight();
// see if there is a sub-grid to create
const node = el.gridstackNode;
if (node.subGridOpts) {
this.makeSubGrid(el, node.subGridOpts, undefined, false); // node.subGrid will be used as option in method, no need to pass
}
// if we're adding an item into 1 column (_prevColumn is set only when going to 1) make sure
// we don't override the larger 12 column layout that was already saved. #1985
if (this._prevColumn && this.opts.column === 1) {
this._ignoreLayoutsNodeChange = true;
}
this._triggerAddEvent();
this._triggerChangeEvent();
delete this._ignoreLayoutsNodeChange;
return el;
}
/**
* Event handler that extracts our CustomEvent data out automatically for receiving custom
* notifications (see doc for supported events)
* @param name of the event (see possible values) or list of names space separated
* @param callback function called with event and optional second/third param
* (see README documentation for each signature).
*
* @example
* grid.on('added', function(e, items) { log('added ', items)} );
* or
* grid.on('added removed change', function(e, items) { log(e.type, items)} );
*
* Note: in some cases it is the same as calling native handler and parsing the event.
* grid.el.addEventListener('added', function(event) { log('added ', event.detail)} );
*
*/
on(name, callback) {
// check for array of names being passed instead
if (name.indexOf(' ') !== -1) {
let names = name.split(' ');
names.forEach(name => this.on(name, callback));
return this;
}
if (name === 'change' || name === 'added' || name === 'removed' || name === 'enable' || name === 'disable') {
// native CustomEvent handlers - cash the generic handlers so we can easily remove
let noData = (name === 'enable' || name === 'disable');
if (noData) {
this._gsEventHandler[name] = (event) => callback(event);
}
else {
this._gsEventHandler[name] = (event) => callback(event, event.detail);
}
this.el.addEventListener(name, this._gsEventHandler[name]);
}
else if (name === 'drag' || name === 'dragstart' || name === 'dragstop' || name === 'resizestart' || name === 'resize' || name === 'resizestop' || name === 'dropped') {
// drag&drop stop events NEED to be call them AFTER we update node attributes so handle them ourself.
// do same for start event to make it easier...
this._gsEventHandler[name] = callback;
}
else {
console.log('GridStack.on(' + name + ') event not supported, but you can still use $(".grid-stack").on(...) while jquery-ui is still used internally.');
}
return this;
}
/**
* unsubscribe from the 'on' event below
* @param name of the event (see possible values)
*/
off(name) {
// check for array of names being passed instead
if (name.indexOf(' ') !== -1) {
let names = name.split(' ');
names.forEach(name => this.off(name));
return this;
}
if (name === 'change' || name === 'added' || name === 'removed' || name === 'enable' || name === 'disable') {
// remove native CustomEvent handlers
if (this._gsEventHandler[name]) {
this.el.removeEventListener(name, this._gsEventHandler[name]);
}
}
delete this._gsEventHandler[name];
return this;
}
/** remove all event handlers */
offAll() {
Object.keys(this._gsEventHandler).forEach(key => this.off(key));
return this;
}
/**
* Removes widget from the grid.
* @param el widget or selector to modify
* @param removeDOM if `false` DOM element won't be removed from the tree (Default? true).
* @param triggerEvent if `false` (quiet mode) element will not be added to removed list and no 'removed' callbacks will be called (Default? true).
*/
removeWidget(els, removeDOM = true, triggerEvent = true) {
GridStack.getElements(els).forEach(el => {
if (el.parentElement && el.parentElement !== this.el)
return; // not our child!
let node = el.gridstackNode;
// For Meteor support: https://github.com/gridstack/gridstack.js/pull/272
if (!node) {
node = this.engine.nodes.find(n => el === n.el);
}
if (!node)
return;
if (GridStack.addRemoveCB) {
GridStack.addRemoveCB(this.el, node, false, false);
}
// remove our DOM data (circular link) and drag&drop permanently
delete el.gridstackNode;
this._removeDD(el);
this.engine.removeNode(node, removeDOM, triggerEvent);
if (removeDOM && el.parentElement) {
el.remove(); // in batch mode engine.removeNode doesn't call back to remove DOM
}
});
if (triggerEvent) {
this._triggerRemoveEvent();
this._triggerChangeEvent();
}
return this;
}
/**
* Removes all widgets from the grid.
* @param removeDOM if `false` DOM elements won't be removed from the tree (Default? `true`).
*/
removeAll(removeDOM = true) {
// always remove our DOM data (circular link) before list gets emptied and drag&drop permanently
this.engine.nodes.forEach(n => {
delete n.el.gridstackNode;
this._removeDD(n.el);
});
this.engine.removeAll(removeDOM);
this._triggerRemoveEvent();
return this;
}
/**
* Toggle the grid animation state. Toggles the `grid-stack-animate` class.
* @param doAnimate if true the grid will animate.
*/
setAnimation(doAnimate) {
if (doAnimate) {
this.el.classList.add('grid-stack-animate');
}
else {
this.el.classList.remove('grid-stack-animate');
}
return this;
}
/**
* Toggle the grid static state, which permanently removes/add Drag&Drop support, unlike disable()/enable() that just turns it off/on.
* Also toggle the grid-stack-static class.
* @param val if true the grid become static.
* @param updateClass true (default) if css class gets updated
* @param recurse true (default) if sub-grids also get updated
*/
setStatic(val, updateClass = true, recurse = true) {
if (!!this.opts.staticGrid === val)
return this;
val ? this.opts.staticGrid = true : delete this.opts.staticGrid;
this._setupRemoveDrop();
this._setupAcceptWidget();
this.engine.nodes.forEach(n => {
this._prepareDragDropByNode(n); // either delete or init Drag&drop
if (n.subGrid && recurse)
n.subGrid.setStatic(val, updateClass, recurse);
});
if (updateClass) {
this._setStaticClass();
}
return this;
}
/**
* Updates widget position/size and other info. Note: if you need to call this on all nodes, use load() instead which will update what changed.
* @param els widget or selector of objects to modify (note: setting the same x,y for multiple items will be indeterministic and likely unwanted)
* @param opt new widget options (x,y,w,h, etc..). Only those set will be updated.
*/
update(els, opt) {
// support legacy call for now ?
if (arguments.length > 2) {
console.warn('gridstack.ts: `update(el, x, y, w, h)` is deprecated. Use `update(el, {x, w, content, ...})`. It will be removed soon');
// eslint-disable-next-line prefer-rest-params
let a = arguments, i = 1;
opt = { x: a[i++], y: a[i++], w: a[i++], h: a[i++] };
return this.update(els, opt);
}
GridStack.getElements(els).forEach(el => {
if (!el || !el.gridstackNode)
return;
let n = el.gridstackNode;
let w = Utils.cloneDeep(opt); // make a copy we can modify in case they re-use it or multiple items
delete w.autoPosition;
// move/resize widget if anything changed
let keys = ['x', 'y', 'w', 'h'];
let m;
if (keys.some(k => w[k] !== undefined && w[k] !== n[k])) {
m = {};
keys.forEach(k => {
m[k] = (w[k] !== undefined) ? w[k] : n[k];
delete w[k];
});
}
// for a move as well IFF there is any min/max fields set
if (!m && (w.minW || w.minH || w.maxW || w.maxH)) {
m = {}; // will use node position but validate values
}
// check for content changing
if (w.content) {
let sub = el.querySelector('.grid-stack-item-content');
if (sub && sub.innerHTML !== w.content) {
sub.innerHTML = w.content;
}
delete w.content;
}
// any remaining fields are assigned, but check for dragging changes, resize constrain
let changed = false;
let ddChanged = false;
for (const key in w) {
if (key[0] !== '_' && n[key] !== w[key]) {
n[key] = w[key];
changed = true;
ddChanged = ddChanged || (!this.opts.staticGrid && (key === 'noResize' || key === 'noMove' || key === 'locked'));
}
}
Utils.sanitizeMinMax(n);
// finally move the widget
if (m) {
this.engine.cleanNodes()
.beginUpdate(n)
.moveNode(n, m);
this._updateContainerHeight();
this._triggerChangeEvent();
this.engine.endUpdate();
}
if (changed) { // move will only update x,y,w,h so update the rest too
this._writeAttr(el, n);
}
if (ddChanged) {
this._prepareDragDropByNode(n);
}
});
return this;
}
/**
* Updates the margins which will set all 4 sides at once - see `GridStackOptions.margin` for format options (CSS string format of 1,2,4 values or single number).
* @param value margin value
*/
margin(value) {
let isMultiValue = (t