can.ui.Sortable API

[justinbmeyer]

Purpose

• A sortable list that can be hooked up to a can.Observe.List for live updates.

  Learn from

• Mxui.Layout.Sortable
• jQuery UI Sortable

  Options

• [containment=null] Element | Selector - A container to constrain dragging of items within. Defaults to the parent.
• [constrain=null] String - Whether to enforce a constrained dragging direction.
  • 'x' - Constrain to the x-axis.
  • 'y' - Constrain to the y-axis.
• [disabled=false] Boolean - Whether sorting is disabled.
• [delay=500] Number - Drag delay in milliseconds prior to starting sorting.
• [distance=1] Number - Drag distance in pixels prior to starting sorting.
• [handle=null] Selector - The selector for a child element to be used as a handle for initializing sorts.
• [helper='original'] String | Function - What element to use for dragging an item.
  • 'original' - Use the original element.
  • 'clone' - Clone the original element.
  • Function - Returns an element to use.
• items can.Observe.List | Array | Deferred | Selector | can.compute
  • can.Observe.List - A list to be used with default markup.
  • Array - An array that will be converted to a list with default markup.
  • Deferred - Sets the sortable to loading state that renders on resolve.
  • Selector - A selector for children of the parent to determine the list of items.
  • can.compute - A compute that returns any of the above.
• parent Element - The containing element for the sortable list.
• [placeholder=null] Element - An element to clone as placeholder elements to fill white space.
• [revert=false] Boolean | Number - Whether to smoothly revert the dragged item with an animation. If set to a Number, the speed in milliseconds at which the revert is animated.
• [scroll=true] Boolean - Whether to auto-scroll when sorting and the mouse comes near an edge of the list.
• [scrollDistance=20] Number - The distance in pixels at which auto-scrolling begins.
• [scrollSpeed=20] Number - The speed in milliseconds at which the sortable auto-scrolls.
• [template=null] View - A template to use to render items when using types other than Selector for items.
• [validate=null] Function - Validates elements dropped onto the sortable from external sources. Default: All drops denied.
• [zIndex=1000] Number - The z-index of the dragged item while sorting.

  Events

• add - An external item has been dropped into the list.
• change - The sortable list has been altered.
• over - An external item is being dragged over the list.
• out - An external item is no longer being dragged over the list.
• sortstart - A sort has been initialized.
• sort - A sort has been updated.
• sortend - A sort has finished.
• remove - An item has been dropped externally and removed.

  Methods

• disable - Disables sorting.
• enable - Enables sorting.

  Theming

• Follows Twitter Bootstrap conventions. Include stylesheets with steal('canui/style').

  Examples

  Creating a sortable:

var sortable = new can.ui.Sortable('#list', {
  items: new can.Observe.List()
});

Basic example:

• TODO

  Using custom helpers:

• TODO

  Using custom helpers to drop multiple items:

• TODO

  Handling drops from external sources:

• TODO

  Listening to sorts and updating DBs:

• TODO: something that listens to the order being changed on an Observe.List and is able to update the DB accordingly (possibly updating some index property).

  Notes

• options.helper's Function type is equivalent to how placeholders were handled in MXUI's Sortable.
• how would we know the instance that is being added via drag-drop?
• support multiple instances?
• pass the list and a view for inside the li?

[andykant]

I edited the issue to include an updated API but still need to add examples.