Resolve "Implement basic functionality"

Closes #1 (closed) Closes #2 (closed) Closes #3 (closed) Closes #4 (closed) Closes #5 (closed) Closes #6 (closed)

docs/guide/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 draggableGrid from "vue-draggable-grid";
+
+Vue.use(draggableGrid);
+
+// Now create your app as usual
+```
+
+An example usage could look like this:
+
+```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.
+
+```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.