Edit on GitHub

Backend sorting and reordering

Introduction

The Reorder behavior is a controller behavior that provides features for sorting and reordering database records. The behavior provides a page called Reorder using the controller action reorder. This page displays a list of records with a drag handle allowing them to be sorted and in some cases restructured.

The behavior depends on a model class which must implement one of the following model traits:

  1. Winter\Storm\Database\Traits\Sortable
  2. Winter\Storm\Database\Traits\NestedTree

NOTE: If adding sorting to a previously unsorted model under the control of a third party is desired, you can use the Winter\Storm\Database\Behaviors\Sortable behavior, which can be dynamically implemented. However, you will need to ensure that the model table has a sort_order column present on it.

In order to use the Reorder behavior you should add the \Backend\Behaviors\ReorderController::class definition to the $implement property of the controller class.

namespace Acme\Shop\Controllers;

class Categories extends Controller
{
    /**
     * @var array List of behaviors implemented by this controller
     */
    public $implement = [
        \Backend\Behaviors\ReorderController::class,
    ];
}

Configuring the behavior

The Reorder behaviour will load its configuration in the YAML format from a config_reorder.yaml file located in the controller's views directory (plugins/myauthor/myplugin/controllers/mycontroller/config_reorder.yaml) by default.

This can be changed by overriding the $reorderConfig property on your controller to reference a different filename or a full configuration array:

public $reorderConfig = 'my_custom_reorder_config.yaml';

Below is an example of a typical Reorder behavior configuration file:

# ===================================
#  Reorder Behavior Config
# ===================================

# Reorder Title
title: Reorder Categories

# Attribute name
nameFrom: title

# Model Class name
modelClass: Acme\Shop\Models\Category

# Toolbar widget configuration
toolbar:
    # Partial for toolbar buttons
    buttons: reorder_toolbar

The configuration options listed below can be used.

Option Description
title used for the page title.
nameFrom specifies which attribute should be used as a label for each record.
modelClass a model class name, the record data is loaded from this model.
toolbar reference to a Toolbar Widget configuration file, or an array with configuration.

Displaying the reorder page

You should provide a view file with the name reorder.htm. This view represents the Reorder page that allows users to reorder records. Since reordering includes the toolbar, the view file will consist solely of the single reorderRender method call.

<?= $this->reorderRender() ?>

Override Sortable Partials

If you need to override default view of your reorder page, you have to copy

  1. modules/backend/behaviors/reordercontroller/partials/_container.htm
  2. modules/backend/behaviors/reordercontroller/partials/_records.htm

in

  1. plugins/yournamespace/yourplugin/yoursortablecontroller/_reorder_container.htm
  2. plugins/yournamespace/yourplugin/yoursortablecontroller/_reorder_records.htm

Extending the model query

The lookup query for the list database model can be extended by overriding the reorderExtendQuery method inside the controller class. This example will ensure that soft deleted records are included in the list data, by applying the withTrashed scope to the query:

public function reorderExtendQuery($query)
{
    $query->withTrashed();
}

Keep informed

Sign up to our newsletter to receive updates on Winter CMS releases, new features in the works, and much more.
We'll never spam or give this address away.

Latest blog post

Winter: 16 Months Later

Published July 14, 2022
With the first year of Winter behind us, let's take a look at what we were able to achieve in 2021.

View this post Read all posts

Latest Winter CMS release

v1.2.1

Released October 20, 2022
14 UX/UI Improvements, 25 API Changes, 33 Bug Fixes, 4 Security Improvements, 5 Translation Improvements, 1 Performance Improvement, 2 Community Improvements, 2 Dependencies, 0 New Contributors * @cstorus made their first contribution in https://github.com/wintercms/winter/pull/616 * @simonmannsfeld made their first contribution in https://github.com/wintercms/winter/pull/623 * @quangtrongonline made their first contribution in https://github.com/wintercms/winter/pull/636 * @nathanlesage made their first contribution in https://github.com/wintercms/winter/pull/665 * @vllvll made their first contribution in https://github.com/wintercms/winter/pull/669 * @robertalexa made their first contribution in https://github.com/wintercms/winter/pull/668 * @iamyigitkoc made their first contribution in https://github.com/wintercms/winter/pull/624 * @hecc127 made their first contribution in https://github.com/wintercms/winter/pull/682 * @prsuhas made their first contribution in https://github.com/wintercms/winter/pull/723

View details View all releases