SuperSort

...a super-duper sorting function for your Craft CMS templates., _(*1)

A Top Shelf Craft creation
Michael Rog, Proprietor, _(*2)

What is SuperSort?

The SuperSort plugin provides a powerful Twig filter that helps with ordering an array of values — either using one of PHP's built-in methods to sort the actual values, or using custom "sort as" methods to arrange the array based on the rendered results of processing each member as a Twig object template., _(*3)

Using SuperSort's "sort as" methods, you can sort an array of elements by any accessible object value — including values from Matrix blocks, attributes of related elements, math calculations, etc., _(*4)

Usage

Installation

Visit the Plugin Store in your Craft control panel, search for SuperSort, and click to Install the plugin., _(*5)

Or, if you're feeling frisky, you can install SuperSort via Composer:, _(*6)

composer require topshelfcraft/supersort

General usage

Use the supersort filter to sort an array of objects., _(*7)

(You can apply supersort to any array or ElementQuery. A non-array-like source will be converted into a single-item array... which probably isn't very useful for sorting.), _(*8)

Basic Sorting

The first parameter of the filter specifies the sort method., _(*9)

{% set sortedSource = source | supersort('asort') %}

You can use any of PHP's built-in sort methods:, _(*10)

If you don't supply this first parameter, a plain vanilla asort will be applied:, _(*11)

{% set sortedSource = source | supersort %}

In many common cases — such as when you're sorting names, numbers, or filenames — the default 'asort' algorithm may produce unwanted results. In those cases, consider using the case-insensitive natural sorting algorithm ('natcasesort')., _(*12)

Advanced ("As") Sorting

You can also sort by one of SuperSort's custom methods:, _(*13)

'sortAs'
'rsortAs'
'natsortAs'
'natcasesortAs'

To use these methods, you will provide a second parameter, which is a Twig object template to render using each object in the array:, _(*14)

{% set upcomingEvents = upcomingEvents | supersort('sortAs', '{eventDates.first.date}') %}

{% set upcomingEvents = upcomingEvents | supersort('sortAs', '{{ object.eventDates.first.date }}') %}

(This "object template" syntax is the same as you might use to define a Dynamic Subfolder Path for an Assets field., _(*15)

Sort Flags

You can optionally provide a third parameter — one of PHP's sort flags., _(*16)

{% set source = source | supersort('sortAs', '{foo}', SORT_NUMERIC) %}

{% set source = source | supersort('asort', null, SORT_NUMERIC) %}

If you don't supply this third parameter, the default (SORT_REGULAR) flag is used., _(*17)

Using SuperSort as a PHP helper

If you'd like to use the superSort() method as a helper in another Craft plugin or component, you can access it in PHP directly from the Sorter service:, _(*18)

$result = Sorter::superSort($array, $method, $as, $sortFlag, $comp);

(Note: PHP's built-in sort methods sort an array in place and return a boolean representing success. The superSort() method, by contrast, returns the result array.), _(*19)