index.md

---
sidebar: auto
---

# Guide

## Quickstart

Install the package `vue-draggable-grid` via your favourite package manager.
Include the library in your project:

```javascript
import plugin from 'vue-draggable-grid';

Vue.use(plugin);

// Now create your app as usual
```

Inside the component where you want to use the grid define your grid and data as follows:

```vue

<template>
  <drag-grid v-model="items" :cols="4" :rows="4">
    <template #item="item">
      {{ item.data.text }}
    </template>
  </drag-grid>
</template>

<script>
export default {
  name: "YourComponent",
  data() {
    return {
      items: [
        {x: 1, y: 3, w: 2, h: 2, key: "item1", data: {text: "Hello world 1"},},
        {x: 2, y: 2, w: 2, h: 1, key: "item2", data: {text: "Hello world 2"},},
        {x: 3, y: 1, w: 1, h: 1, key: "item3", data: {text: "Hello world 3"},},
      ]
    }
  },
}
</script>
```

## Blocking fields

A field (or cell) can be blocked via the `disabledFields` prop. The prop receives an array of objects, containing the
coordinates of the blocked fields.

An example for a disabled fields property:

```javascript
disabledFields: [
    {x: 1, y: 1},
    {x: 2, y: 3},
]
```

## Prevent items from being dragged

To disable dragging of a specific item, simply set the attribute `disabled` of the item to `true`.

```javascript{4,5}
someDisabledItems: [
    { key: "key1", x: 1, y: 3, w: 1, h: 1, data: {} },
    { key: "key2", x: 2, y: 2, w: 1, h: 1, data: {} },
    { key: "key3", x: 3, y: 1, w: 1, h: 1, data: {}, disabled: true },
    { key: "key4", x: 1, y: 2, w: 1, h: 1, data: {}, disabled: true },
]
```

The highlighted items are not draggable.

## Disabling the grid

If the boolean property `disabled` is set for the whole grid, the grid itself is disabled,
and items can't be moved.

::: tip NOTICE
A disabled grid only prevents changing the data inside the grid. If the data changes from outside
of the grid, the grid _will_ rerender.
:::

## Programmatic validation of movements

It is also possible to supply a function to dynamically or programmatically hinder fields from being moved to,
and items from being moved. This can be done by supplying a function which takes the `x` and `y` coordinates of
the field as well as the key of the item. If `false` is returned, the movement is prohibited. The highlight which
appears when dragging an element is also disabled for this field.

Examples for such methods are the following:

```javascript
function blockField(x, y, key) {
    // We won't move items with ID 'obj8' and nothing into (3, 3) and (4, 3)
    if (x === 3 && y === 3) return false;
    if (x === 4 && y === 3) return false;
    return key !== "obj8";
};

function blockAllMoving() {
    return false;
};
```

## Changing the highlight

The highlight is the grey-bordered rectangle which appears when dragging over a field.

### Custom highlight

To customize the highlight, use the `highlight` slot inside the grid component.

```html

<drag-grid
        v-model="items"
        :cols="3"
        :rows="2"
>
    <template #highlight>
        <div ref="highlight" class="custom-highlight">
            This is a custom highlight with a custom style!
        </div>
    </template>
</drag-grid>
```

### Disabled highlight

To disable the highlight, use the `no-highlight` prop.

## Displaying the loading of items

If the grid is supplied with the `loading` prop, it will be in a loading status. In this status it is
disabled, like if `disabled` where true, but the grid is filled with elements inside the `loader` slot.
This provides the ability to do something like more realistic skeleton loaders.

## Changing items on move

It is possible to make changes to an item once it moved successfully. One can supply a function in the
`validate-element` prop which gets called on a moved item and can make (in place) changes to it. Such a
function could look like this:

```javascript
function randomKey(element) {
    if (element.key.length !== 1) return;
    element.key += Math.random().toString(36).replace("0.", "");
};
```

This method changes the key of a moved item to a random string if the key has a length of 1.
This is used inside example 2 (the tic-tac-toe game).

## Functional item properties

Properties of items don't have to be Numbers, Strings and Objects, they can also be functions
returning those types. They will automatically be called with a grid object containing the `gridId`
as well as the `context`.

A singular item could look like this:

```javascript
[{
  x: (grid) => {
    return grid.gridId === "lesson-plan" ? this.lesson1X : 0;
  },
  y: (grid) => {
    return grid.gridId === "lesson-plan" ? this.lesson1Y : 0;
  },
  w: 1,
  h: this.lesson1Length,
  key: "lesson1",
  data: {
    text: this.lessonData.lesson1,
  },
}]
```

Items can also have custom extra properties. They will however be reset after moving.
An example where these are used is Example 5.

## Listening to grid changes

There are two ways to process changes made by dragging and dropping items: the `input` event
and the `itemChanged` event.

The `input` event works together with the value prop so one can use `v-model` to supply the grid
and have changes made automatically. The event returns the grid how it would look if the item
moved to the specific location.

::: warning 
Notice that this event is only possible if your item properties are basic types, functional items are not
supported and the properties will be reset to `undefined`.
:::

The `itemChanged` event returns the moved item with following attributes:

```javascript
let eventData = {
    context: String,      // Context of the origin grid (same as the target's)
    data: Object,         // Data Object of the item
    gridId: String,       // ID of the target grid
    h: Number,            // Height of the item
    key: String,          // Key of the item
    mouseX: Number,       // Mouse position on the element relative to
    mouseY: Number,       //    the center of the top left rectangle
    originGridId: String, // ID of the origin grid
    w: Number,            // Width of the item
    x: Number,            // New x position (col) of the item
    y: Number,            // New y position (row) of the item
}
```

This event doesn't change the grid, this change has to be made separately. This is 
useful if e.g. a direct API request is needed.

## Multiple grids

To connect multiple grids they need to have the same context. If you supply the same string to the
`context` prop of two grids, the items can be moved interchangeably.

::: warning
Items are not deleted from the source grid if moved to a different one. You have to build a mechanism for this yourself.
Examples for such a mechanism can be found in Examples 4 and 5.
:::

To handle movements from one grid to another, the attributes `gridId` and `originGridId` of the event will help.