Yii 2 Sortable

Thankful to Krajee!
to get more out of us.

NOTE: This extension depends on the kartik-v/yii2-krajee-base extension which in turn depends on the yiisoft/yii2-bootstrap extension. Check the composer.json for this extension's requirements and dependencies that may be updated by composer.

The yii2-sortable extension is primarily a widget that allows you to create sortable lists and grids and manipulate them using simple drag and drop. It is based on the lightweight html5sortable jQuery plugin, which uses the native HTML5 API for drag and drop. It is a leaner alternative for the JUI Sortable plugin and offers very similar functionality. The yii2-sortable widget offers these features:
  • Less than 1KB of javascript used (minified and gzipped).
  • Built using native HTML5 drag and drop API.
  • Supports both list and grid style layouts.
  • Similar API and behaviour to jquery-ui sortable plugin.
  • Works in IE 5.5+, Firefox 3.5+, Chrome 3+, Safari 3+ and, Opera 12+.

The preferred way to install this extension is through composer. Either run:

$ php composer.phar require kartik-v/yii2-sortable "*"

or add:

"kartik-v/yii2-sortable": "*"

to the require section of your composer.json file. Then run:

php composer.phar update

to get the updated package on your application install.

The Sortable widget allows you to configure the following properties:
  • type: string, the type of the sortable widget. Defaults to Sortable::TYPE_LIST. Should be one of

    • Sortable::TYPE_LIST or list

    • Sortable::TYPE_GRID or grid

  • connected: boolean, whether this widget is connected to another Sortable widget. Defaults to false.

  • disabled: boolean, whether this widget is disabled after rendering. Defaults to false.

  • showHandle: boolean, whether to show handle for each sortable item. Defaults to false.

  • handleLabel: string, the label to show for the handle when showHandle is set to true. This is not HTML encoded. Defaults to <i class="glyphicon glyphicon-move"><i> .

  • itemOptions: array the HTML attributes to be applied to all items. This will be merged with and be overridden by the options property set within items configuration.

  • items: array the sortable items configuration for rendering elements within the sortable list / grid. You can set the following properties:

    • content: string, the list item content (this is not HTML encoded).

    • disabled: boolean, whether the list item is disabled.

    • options: string, the HTML attributes for the list item. This will be merged with and override the itemOptions property set at the widget level.

  • options: array the HTML attributes for the main sortable widget container.

  • pluginOptions: array the JQuery plugin options for the html5sortable plugin. You can control many options for the plugin. Refer the plugin documentation for details.

  • pluginEvents: array the bootstrap-sortable plugin events. You must define events in event-name => event-function format. Refer the plugin documentation for details. The most important event in this plugin is sortupdate, which is triggered when the user stopped sorting and the DOM position has changed. All events will be stacked in the sequence passed. For example:

    pluginEvents = [
        'sortupdate' => 'function() { log("sortupdate"); }',
    ];
    

  • Item 1
  • Item 2
  • Item 3
  • Item 4
A sortable list. Drag and drop items to sort.

  • Item 1
  • Item 2
  • Item 3
  • Item 4
  • Item 5
  • Item 6
  • Item 7
  • Item 8
  • Item 9
  • Item 10
A sortable grid with formatted item content.

  • Item 1
  • Item 2
  • Item 3
  • Item 4
A sortable list with handles.

  • Item 1
  • Item 2
  • Item 3
  • Item 4
A sortable list with disabled items.

  • Item 1
  • Item 2
  • Item 3
  • Item 4
Disable entire sortable widget on load.

  • From Item 1
  • From Item 2
  • From Item 3
  • From Item 4
 
  • To Item 1
  • To Item 2
  • To Item 3
  • To Item 4
Two connected Sortable lists with custom styles.
use kartik\sortable\Sortable;

// A sortable list.
echo Sortable::widget([
    'items'=>[
        ['content'=>'Item 1'],
        ['content'=>'Item 2'],
        ['content'=>'Item 3'],
        ['content'=>'Item 4'],
    ]
]);
// A sortable grid with formatted item content.
echo Sortable::widget([
    'type'=>'grid',
    'items'=>[
        ['content'=>'<div class="grid-item text-danger">Item 1</div>'],
        ['content'=>'<div class="grid-item text-danger">Item 2</div>'],
        ['content'=>'<div class="grid-item text-danger">Item 3</div>'],
        ['content'=>'<div class="grid-item text-danger">Item 4</div>'],
        ['content'=>'<div class="grid-item text-danger">Item 5</div>'],
        ['content'=>'<div class="grid-item text-danger">Item 6</div>'],
        ['content'=>'<div class="grid-item text-danger">Item 7</div>'],
        ['content'=>'<div class="grid-item text-danger">Item 8</div>'],
        ['content'=>'<div class="grid-item text-danger">Item 9</div>'],
        ['content'=>'<div class="grid-item text-danger">Item 10</div>'],
    ]
]);
// A sortable list with handles.
echo Sortable::widget([
    'showHandle'=>true,
    'items'=>[
        ['content'=>'Item 1'],
        ['content'=>'Item 2'],
        ['content'=>'Item 3'],
        ['content'=>'Item 4'],
    ]
]);
// A sortable list with disabled items.
echo Sortable::widget([
    'items'=>[
        ['content'=>'Item 1'],
        ['content'=>'Item 2'],
        ['content'=>'Item 3', 'disabled'=>true],
        ['content'=>'Item 4', 'disabled'=>true],
    ]
]);
// Disable entire sortable widget on load.
echo Sortable::widget([
    'disabled'=>true,
    'itemOptions'=>['class'=>'disabled'],
    'items'=>[
        ['content'=>'Item 1'],
        ['content'=>'Item 2'],
        ['content'=>'Item 3'],
        ['content'=>'Item 4'],
    ]
]);
// Two connected Sortable lists with custom styles.
echo Sortable::widget([
    'connected'=>true,
    'items'=>[
        ['content'=>'From Item 1'],
        ['content'=>'From Item 2'],
        ['content'=>'From Item 3'],
        ['content'=>'From Item 4'],
    ]
]);
echo Sortable::widget([
    'connected'=>true,
    'itemOptions'=>['class'=>'alert alert-warning'],
    'items'=>[
        ['content'=>'To Item 1'],
        ['content'=>'To Item 2'],
        ['content'=>'To Item 3'],
        ['content'=>'To Item 4'],
    ]
]);
echo '<div class="clearfix"></div>';

yii2-sortable is released under the BSD 3-Clause License. See the bundled LICENSE.md for details.