Vue Grid Designer

A Vue 2.x component for designing grid layouts using Sortable.js.

Design a responsive grid based on rows and blocks using HTML5 drag and drop. The JSON model can be used to generate an actual HTML grid using any CSS framework you choose or saved to a database for subsequent use. It can be decorated with any additional JSON properties to allow you to extend your grid in any way you need.

Table of Contents

• Dependencies
• Installation
• Usage
  • Grid Data Model
    • Internal model
  • Component Props
  • Overidden Sortable JS Options
  • Events
  • Methods
  • CSS and Styles
    • CSS Classes Used
    • Specificity and Overriding Scoped Styles
    • Using :hover styles
• Demo
• Contributing
• Credits
  • Author
  • Contributors
• Licence

Dependencies

vue-grid-designer has no external dependency requirements. The following dependencies are included in the exported ESM package:

{
    "@fortawesome/fontawesome-svg-core"  : "^1.2.30",
    "@fortawesome/free-solid-svg-icons"  : "^5.14.0",
    "@fortawesome/vue-fontawesome"       : "^2.0.0",
    "lodash-es"                          : "^4.17.15",
    "sortablejs"                         : "^1.10.2",
    "uuid"                               : "^8.3.0",
    "vue"                                : "^2.6.12"
}

Installation

npm i @thefoot/vue-grid-designer --save

Usage

Either register vue-grid-designer as a global component in your main Vue application file:

import Vue             from 'vue';
import VueGridDesigner from '@thefoot/vue-grid-designer';
Vue.component('vue-grid-designer', VueGridDesigner);

new Vue (
    {
        render: h => h ( App )
    }
).$mount ( '#app' );

or use locally (recommended) in your Vue component:

import VueGridDesigner from '@thefoot/vue-grid-designer';

export default {
    ...
    components: { VueGridDesigner }
    ...
};

Then simply add the component to your template and bind your grid model to it:

<template>
    <div>
        <vue-grid-designer v-model="grid"></vue-grid-designer>
    </div>
</template>

<script>
    import VueGridDesigner from '@thefoot/vue-grid-designer';
    export default { 
        components: { VueGridDesigner },
        data () {
            return {
                grid: []
            };
        }   
    };
</script>

You can even use it via a script tag:

<script src="https://unpkg.com/vue"></script>
<script src="https://unpkg.com/@thefoot/vue-grid-designer"></script>

Grid Data Model

The grid is a collection of row objects. row.blocks is a collection of block objects.

[
    {
        blocks: [
            { 
                span: 1,
                content: '<p>Foo</p>'
            }
        ]
    }
]

It is structured this way to allow rows and blocks to be decorated with additional properties. Use-cases are most likely to need additional data.

Internal model

Internally - VDG adds an _id property to each row and block (v4 UUID). Custom events include the ID, whereas the bound model only emits exactly what was passed in, including any custom properties. To retrieve the full internal model, including custom properties, call the getFullModel () component method.

Component Props

| Name | Attr | Type | Default | Description | |-----------------------------|---------------------------------|---------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | mode | mode | String | edit | Component mode - edit or view. View mode hides row and block controls, and displays any content passed in via block.content. | | blocksPerRow | blocks-per-row | Number | 4 | Logical blocks per row. Each block can consume more than one logical block via span - like a table. But, like a responsive grid, you can exceed this number if you wish. | | maxRows | max-rows | Number | 0 | Maximum number of rows. 0 to disable. If you pass in a grid that exceeds this number, it will still display all rows, however if you remove the rows, you cannot add them back. | | rowClass | row-class | String | | Pass in an additional CSS class for the grid row. | | blockClass | block-class | String | | Pass in an additional CSS class for the grid block. | | minBlockHeight | min-block-height | Number | 100 | Minimum block height in pixels. | | blockMargin | block-margin | Number | 6 | Block margin in pixels. | | enableMoveBlocksBetweenRows | enable-more-blocks-between-rows | Boolean | true | Allow blocks to be moved between different rows. Setting to false restricts blocks to their own row. | | sortableOptions | sortable-options | Object | {} | Native options passed directly through to the SortableJS constructor. Some options are overridden (see table below). | | onNewRow | on-new-row | Function | | Callback for creating a custom row object. No parameters. Return a new row object. | | onNewBlock | on-new-block | Function | | Callback for creating a custom block object. Receives ( row, span ) params. Return a new block object. |

Overidden Sortable JS Options

| Prop | Attr | SortableJS Option | Type | Default | Description | |---------------------|-----------------------|-------------------|----------|----------------------|----------------------------------------------------------------------------| | sortableGhostClass | sortable-ghost-class | ghostClass | String | vgd__block--ghost | CSS class applied to the ghost element. | | sortableChosenClass | sortable-chosen-class | chosenClass | String | vgd__block--chosen | CSS class applied to the chosen element. | | sortableDragClass | sortable-drag-class | dragClass | String | vgd__block--drag | CSS class applied to the dragged element. | | sortableAnimation | sortable-animation | animation | Number | 50 | Animation speed in ms. 0 to disable animations. | | | - | disabled | Boolean | - | Based on the mode prop. In view mode, the DnD functionality is disabled. | | | - | group | String | vgd | Based on the enableMoveBlocksBetweenRows prop. | | | - | filter | String | .no-drag | Used to disable grid elements from being dragged (toolbars). | | | - | preventOnFilter | Boolean | true | Related to filter. | | | - | onUpdate | Function | - | Used internally. See events table below. | | | - | onRemove | Function | - | Used internally. See events table below. | | | - | onAdd | Function | - | Used internally. See events table below. | | | - | onStart | Function | - | Used internally. See events table below. | | | - | onEnd | Function | - | Used internally. See events table below. |

Events

All events have a vgd property added to the original event (either SortableJS event or native event - whichever is relevant), and contain row and block properties.

| Name | Description | Example | |--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| | ready | Fired when the grid is initialised and ready for use. No event data is emitted. | | | update | Fired after a block has been moved. Only fired when a block is moved within a row. When block is moved between rows, remove-block and add-block events are fired. | vue-grid-designer @update="updateHandler" /> | | remove-block | Fired after a block has been removed. | vue-grid-designer @remove-block="removeBlockHandler" /> | | remove-row | Fired after a row has been removed. | vue-grid-designer @remove-row="rowRemoveHandler" /> | | add-block | Fired after a new block has been added. | vue-grid-designer @add-block="addBlockHandler" /> | | add-row | Fired after a new row has been added. | vue-grid-designer @add-row="addRowHandler" /> | | drag-start | Fired when a drag action has started. | vue-grid-designer @drag-start="dragStartHandler" /> | | drag-stop | Fired when a drag action has ended. | vue-grid-designer @drag-stop="dragStopHandler" /> | | block-changed| Fired when a block has been expanded or collapsed. | vue-grid-designer @block-changed="blockChangedHandler" /> | | input | Fired by Vue implicitly for v-model support. | - |

Methods

Methods that receive an event parameter fire a custom event.

| Name | Params | Description | |-------------------|----------------------------------|-------------------------------------------------------------------------------------------| | getFullModel | () | Return the full internal model including custom properties.| | addRow | ( event ) | Append a new row to the grid. | | addBlock | ( event, row, span = 1 ) | Append a new block to a row. | | deleteRow | ( event, row ) | Delete a row from the grid. | | deleteBlock | ( event, row, block ) | Delete a block from a row. | | expandBlock | ( event, row, block, num = 1 ) | Decrease the span for a given block. | | collapseBlock | ( event, row, block, num = 1 ) | Increase the span for a given block. | | getEventData | ( event, sourceRow = 'from' ) | Return a vgd info object for a given event. sourceRow can be from or to. | | getBlockStyles | ( row, block ) | Return a style object for a given block. Can be used with :style="getBlockStyles(...)". | | getAnimationStyle | () | Return the animation style object. Can be used with :style="getAnimationStyle()". | | initGrid | () | Initialise the grid. Called from mounted(). | | initSortableRow | ( row ) | Initialise the SortableJS plugin for a given row. | | fireChanged | () | Trigger the input event. Used for v-model support. |

CSS and Styles

This component uses BEM methodology and naming convention.

CSS Classes Used

| CSS Class | Element | Description | |-------------------------------|-------------------------------------------------|----------------------------------------| | vgd__row | Row | | | vgd__block | Block | | | vgd__block__toolbar | Block toolbar | | | vgd__block__toolbar__button | Block toolbar icon button | | | vgd__block__content | Block content | | | vgd__row__toolbar | Row toolbar | | | vgd__row__toolbar__button | Row toolbar icon button | | | vgd__footer__button | Add row button | | | vgd__block--ghost | Block variant for the sortable ghost element. | | | vgd__block--chosen | Block variant for the sortable chosen element. | | | vgd__block--drag | Block variant for the sortable dragged element. | | | use-hover | Row | See note below on using :hover styles. |

Specificity and Overriding Scoped Styles

For scoped styles, Vue uses a data attribute based on the component ID to isolate styles to the component. In order to override these styles you should prefix all style overrides using your main app or component selector. E.g.:

#demo {
    .vgd__row { ... }
}

For additional examples, please look at the Demo source code.

Using :hover styles

There is a known issue with :hover state in DnD elements in Chrome. The workaround is to scope any :hover styles. This scope is provided via the .use-hover class. E.g.:

.use-hover {
    .vgd__row:hover { ... }
}

Demo

Component Demo

Contributing

Contributions welcome, please read CONTRIBUTING and CODING-STANDARDS.

Credits

Author

• @TheFoot

Contributors

• .

Licence

MIT