Customise preview

There are two situations you want to use customised preview.

1. when the built-in preview drawer doesn’t draw preview to your expectation, either due to css limitation or DOM hierarchy limitation.
2. when you want a totally different preview, for instance, customise “cursor” during DnD session.

DnD source delegate has an optional callback dndPreview(model) to draw customised preview. The input is the model generated by dndModel(), the output needs to be a DOM element (not attached to DOM tree yet).

In this tutorial, we use jQuery (not required) to create DOM element.

For “Box” and “Money” buttons, we use dndPreview() to customise preview.

In customised preview mode, DndService only sets left and top on the preview element, not width or height. You need to make sure your element has reasonable size.

By default, preview is aligned to source element’s top left corner.

You can centre your preview element around mouse position instead of aligning to source element top left corner. dndService.addSource(this, {centerPreviewToMousePosition: true});

This centerPreviewToMousePosition option works in both default preview and customised preview.

There is one more option you can pass to addSource(): hideCursor, which is to hide cursor during a DnD session.

Combine option centerPreviewToMousePosition with hideCursor, you are essentially using dndPreview() to draw a cursor replacement! That’s what happened behind “Money” button.

You could do conditional customising. In dndPreview() callback, return a DOM element when you need to customise preview, or return null/undefined when you want to fall back to default preview.

Style target element based on DnD state

In the above example code, both boxes and container are DnD targets. They got some style change during a DnD session.

Let’s have a look on the implementation of box’s property dndCss.

@computedFrom('dnd', 'dnd.model', 'dnd.isProcessing', 'dnd.canDrop', 'dnd.isHoveringShallowly')
get dndCss() {
  if (!this.dnd) return '';
  const {model, isProcessing, canDrop, isHoveringShallowly} = this.dnd;
  if (!isProcessing) return '';
  // no style if moving item
  if (model.type === 'moveItem') return '';
  let css = '';
  if (canDrop) {
    css += 'can-drop';
  } else {
    css += 'can-not-drop';
  }
  if (isHoveringShallowly) css += ' shallow-hover';
  return css;
}

It observes dnd.isProcessing, dnd.model, dnd.canDrop and dnd.isHoveringShallowly, set the right css class for box element. Thanks for Aurelia, all the style changes are updated automatically during a DnD session.

Optional source handler

You can pass a handler element to addSource() options. handler should be an DOM element within the source element, it only limits where the drag can start, doesn’t affect how preview was drawn.

Default preview still clones source element, not handler element.

Preview still aligns to source element, not handler element.

Prevent preview to show some parts

You can mark parts of the source element with class bcx-dnd-preview-hide to prevent the part showing up in preview. For instance, mark edit button to hide it in preview.

The default style for bcx-dnd-preview-hide is visibility: hidden;, not display: none;, this makes sure the hidden part doesn’t affect the layout geometry.

.bcx-dnd-preview .bcx-dnd-preview-hide {
  visibility: hidden !important;
}

Here is an example for both source handler and bcx-dnd-preview-hide.

That concludes all features of bcx-aurelia-dnd.