Sortable JAVASCRIPT UI Component API

Sortable Javascript API

Class

Sortable

Sortable

Sortable allows you to rearrange a group of html elements.

Selector

smart-sortable

Properties

AanimationSets or gets the animation mode. Animation is disabled when the property is set to 'none'
DdisabledEnables or disables sorting.
DdragModeSets or gets the way a sortable item can be dragged - by dragging the item itself ('item') or by dragging a handle that appears next to the item ('handle').
HhandlePositionSets or gets the the position of the drag handle relative to its respective sortable item. Applicable only when dragMode is 'handle'.
HhandleVisibilitySets or gets whether a sortable item's drag handle is always visible or is shown when the item is hovered. Applicable only when dragMode is 'handle'.
IitemsSets or gets a selector to determine the sortable items by. By default, sortable items are all children of the smart-sortable custom element.
LlocaleSets or gets the language. Used in conjunction with the property messages.
LlocalizeFormatFunctionCallback, related to localization module.
MmessagesSets or gets an object specifying strings used in the widget that can be localized. Used in conjunction with the property locale.
MmodeSets or gets the direction sortable items are stacked and can be dragged.
RrightToLeftSets or gets the value indicating whether the element is aligned to support locales using right-to-left fonts.

Events

DdragEndThis event is triggered when sortable items have been reordered.

Methods

MmoveMoves a sortable item from one index to another.
UupdateItemsRe-evaluates the items that can be sorted. Useful after items have been added to or removed from the custom element.

Properties

animation"none" | "simple" | "advanced"

Sets or gets the animation mode. Animation is disabled when the property is set to 'none'

Allowed Values

  • "none" - animation is disabled
  • "simple" - ripple animation is disabled
  • "advanced" - all animations are enabled

Default value

"advanced"

Example

Set the animation property. 

 <smart-sortable animation='none'></smart-sortable>

Set the animation property by using the HTML Element's instance. 

 const sortable = document.querySelector('smart-sortable');
 sortable.animation = 'simple';

Get the animation property. 

 const sortable = document.querySelector('smart-sortable');
 let animation = sortable.animation;

disabledboolean

Enables or disables sorting.

Default value

false

Example

Set the disabled property. 

 <smart-sortable disabled></smart-sortable>

Set the disabled property by using the HTML Element's instance. 

 const sortable = document.querySelector('smart-sortable');
 sortable.disabled = false;

Get the disabled property. 

 const sortable = document.querySelector('smart-sortable');
 let disabled = sortable.disabled;

dragMode"item" | "handle"

Sets or gets the way a sortable item can be dragged - by dragging the item itself ('item') or by dragging a handle that appears next to the item ('handle').

Default value

"item"

Example

Set the dragMode property. 

 <smart-sortable drag-mode='handle'></smart-sortable>

Set the dragMode property by using the HTML Element's instance. 

 const sortable = document.querySelector('smart-sortable');
 sortable.dragMode = 'item';

Get the dragMode property. 

 const sortable = document.querySelector('smart-sortable');
 let dragMode = sortable.dragMode;

handlePosition"right" | "left" | "top" | "bottom"

Sets or gets the the position of the drag handle relative to its respective sortable item. Applicable only when dragMode is 'handle'.

Default value

"right"

Example

Set the handlePosition property. 

 <smart-sortable handle-position='top'></smart-sortable>

Set the handlePosition property by using the HTML Element's instance. 

 const sortable = document.querySelector('smart-sortable');
 sortable.handlePosition = 'left';

Get the handlePosition property. 

 const sortable = document.querySelector('smart-sortable');
 let handlePosition = sortable.handlePosition;

handleVisibility"hover" | "visible"

Sets or gets whether a sortable item's drag handle is always visible or is shown when the item is hovered. Applicable only when dragMode is 'handle'.

Default value

"hover"

Example

Set the handleVisibility property. 

 <smart-sortable handle-visibility='visible'></smart-sortable>

Set the handleVisibility property by using the HTML Element's instance. 

 const sortable = document.querySelector('smart-sortable');
 sortable.handleVisibility = 'hover';

Get the handleVisibility property. 

 const sortable = document.querySelector('smart-sortable');
 let handleVisibility = sortable.handleVisibility;

itemsstring | null

Sets or gets a selector to determine the sortable items by. By default, sortable items are all children of the smart-sortable custom element.

Example

Set the items property. 

 <smart-sortable items='li'></smart-sortable>

Set the items property by using the HTML Element's instance. 

 const sortable = document.querySelector('smart-sortable');
 sortable.items = .special-item;

Get the items property. 

 const sortable = document.querySelector('smart-sortable');
 let items = sortable.items;

localestring

Sets or gets the language. Used in conjunction with the property messages.

Default value

"en"

Example

Set the locale property. 

 <smart-sortable locale='de'></smart-sortable>

Set the locale property by using the HTML Element's instance. 

 const sortable = document.querySelector('smart-sortable');
 sortable.locale = 'en';

Get the locale property. 

 const sortable = document.querySelector('smart-sortable');
 let locale = sortable.locale;

localizeFormatFunctionfunction | null

Callback, related to localization module.

Example

Set the localizeFormatFunction property. 

 <smart-sortable localize-format-function='function(){return '...'}'></smart-sortable>

Set the localizeFormatFunction property by using the HTML Element's instance. 

 const sortable = document.querySelector('smart-sortable');
 sortable.localizeFormatFunction = function(){return '...'};

Get the localizeFormatFunction property. 

 const sortable = document.querySelector('smart-sortable');
 let localizeFormatFunction = sortable.localizeFormatFunction;

messagesobject

Sets or gets an object specifying strings used in the widget that can be localized. Used in conjunction with the property locale.

Default value




"en": {

"propertyUnknownType": "'{{name}}' property is with undefined 'type' member!",

"propertyInvalidValue": "Invalid '{{name}}' property value! Actual value: '{{actualValue}}', Expected value: '{{value}}'!",

"propertyInvalidValueType": "Invalid '{{name}}' property value type! Actual type: '{{actualType}}', Expected type: '{{type}}'!",

"methodInvalidValueType": "Invalid '{{name}}' method argument value type! Actual type: '{{actualType}}', Expected type: '{{type}}' for argument with index: '{{argumentIndex}}'!",

"methodInvalidArgumentsCount": "Invalid '{{name}}' method arguments count! Actual arguments count: '{{actualArgumentsCount}}', Expected at least: '{{argumentsCount}}' argument(s)!",

"methodInvalidReturnType": "Invalid '{{name}}' method return type! Actual type: '{{actualType}}', Expected type: '{{type}}'!",

"elementNotInDOM": "Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.",

"moduleUndefined": "Module is undefined.",

"missingReference": "{{elementType}}: Missing reference to '{{files}}'.",

"htmlTemplateNotSuported": "{{elementType}}: Web Browser doesn't support HTMLTemplate elements.",

"invalidTemplate": "{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."

}

Example

Set the messages property. 

 <smart-sortable messages='{"de":{"propertyUnknownType":"'{{name}}' Eigenschaft ist mit undefined 'Typ'-Member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: '{{actualValue}}', Expected value: '{{value}}'!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: '{{actualType}}', Expected type: '{{type}}'!","methodInvalidValueType":"Invalid '{{name}}' method argument value type! Actual type: '{{actualType}}', Expected type: '{{type}}' for argument with index: '{{argumentIndex}}'!","methodInvalidArgumentsCount":"Invalid '{{name}}' method arguments count! Actual arguments count: '{{actualArgumentsCount}}', Expected at least: '{{argumentsCount}}' argument(s)!","methodInvalidReturnType":"Invalid '{{name}}' method return type! Actual type: '{{actualType}}', Expected type: '{{type}}'!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Web Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."}}'></smart-sortable>

Set the messages property by using the HTML Element's instance. 

 const sortable = document.querySelector('smart-sortable');
 sortable.messages = {"en":{"propertyUnknownType":"'{{name}}' property is with undefined 'type' member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: '{{actualValue}}', Expected value: '{{value}}'!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: '{{actualType}}', Expected type: '{{type}}'!","methodInvalidValueType":"Invalid '{{name}}' method argument value type! Actual type: '{{actualType}}', Expected type: '{{type}}' for argument with index: '{{argumentIndex}}'!","methodInvalidArgumentsCount":"Invalid '{{name}}' method arguments count! Actual arguments count: '{{actualArgumentsCount}}', Expected at least: '{{argumentsCount}}' argument(s)!","methodInvalidReturnType":"Invalid '{{name}}' method return type! Actual type: '{{actualType}}', Expected type: '{{type}}'!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Module is undefined.","missingReference":"{{elementType}}: Missing reference to '{{files}}'.","htmlTemplateNotSuported":"{{elementType}}: Web Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."}};

Get the messages property. 

 const sortable = document.querySelector('smart-sortable');
 let messages = sortable.messages;

mode"horizontal" | "vertical"

Sets or gets the direction sortable items are stacked and can be dragged.

Default value

"vertical"

Example

Set the mode property. 

 <smart-sortable mode='horizontal'></smart-sortable>

Set the mode property by using the HTML Element's instance. 

 const sortable = document.querySelector('smart-sortable');
 sortable.mode = 'vertical';

Get the mode property. 

 const sortable = document.querySelector('smart-sortable');
 let mode = sortable.mode;

rightToLeftboolean

Sets or gets the value indicating whether the element is aligned to support locales using right-to-left fonts.

Default value

false
Try a demo showcasing the rightToLeft property.

Example

Set the rightToLeft property. 

 <smart-sortable right-to-left></smart-sortable>

Set the rightToLeft property by using the HTML Element's instance. 

 const sortable = document.querySelector('smart-sortable');
 sortable.rightToLeft = true;

Get the rightToLeft property. 

 const sortable = document.querySelector('smart-sortable');
 let rightToLeft = sortable.rightToLeft;

Events

dragEndCustomEvent

This event is triggered when sortable items have been reordered.

  • Bubbles Yes
  • Cancelable Yes
  • Interface CustomEvent
  • Event handler property onDragEnd

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Example

Set up the event handler of dragEnd event. 

const sortable = document.querySelector('smart-sortable');
sortable.addEventListener('dragEnd', function (event) {
	// event handling code goes here.
})

Methods

move( fromIndex?: number, toIndex?: number): void

Moves a sortable item from one index to another.

Arguments

fromIndex?number

The original index of the item.

toIndex?number

The index to move the item to.


Invoke the move method.

const sortable = document.querySelector('smart-sortable');
sortable.move("0, 5");

updateItems(): void

Re-evaluates the items that can be sorted. Useful after items have been added to or removed from the custom element.


Invoke the updateItems method.

const sortable = document.querySelector('smart-sortable');
sortable.updateItems();

CSS Variables

--smart-sortable-handle-sizevar()

Default value

"25px"

smartSortable handle size