diff --git a/docs/guide/index.md b/docs/guide/index.md index 724a7742bced14644c78df3aa64478b7bd76a803..3f9a9c727b1675ab27da91627c24a2e4097081a0 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -78,3 +78,68 @@ The highlighted items are not draggable. If the boolean property `disabled` is set for the whole grid, the grid itself is disabled, and items can't be moved. + +## 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. + +## 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).