readme.md

Kirby Alphabetise Plugin

The Kirby Alphabetise Plugin processes a Kirby CMS $page or $tag array and returns a new array that is organized alphabetically or numerically with labeled subsections.

This project is based on a fork of shoesforindustry/kirby-plugins-alphabetise by Russ Baldwin.

Compatible with both Kirby 3 and Kirby 4.

Installation

Clone

1. Clone this repository.
2. Move the folder to site/plugins
3. Rename the folder to alphabetise

Download

1. Download this repository.
2. Decompress the master.zip archive.
3. Move the folder to site/plugins
4. Rename the folder to alphabetise

Usage

1. Create a list of child pages using a key value

The first argument you pass is the sorted $page or $tag array you want to alphabetise.

The key argument of the second array determines what to alphabetise by.

This argument should be a string like title or date. ^{Note 1}

The values passed to sortBy and key are usually the same.

For example, you would include this in your template:

<?php $alphabetise = alphabetise($page->children()->listed()->sortby('title'), array('key' => 'title')); ?>

2. Loop through the returned results and display them

<?php foreach($alphabetise as $letter => $items) : ?>
    <h2><?= str::upper($letter) ?></h2>
    <ul>
    <?php foreach($items as $item): ?>
        <li>
            <a href="<?= $item->url()?>">
            <?= $item->title()?>
            </a>
        </li>
    <?php endforeach ?>
    </ul>
<?php endforeach ?>

Result:

• 1
  • 1a
  • 1b
• 2
  • 2a
  • 2b
• A
  • Aa
  • Ab
• B
  • Ba
  • Bb

3. Optionally set the sort order

The sort order is specified by using the orderby flag when calling the alphabetise function. ^{Note 2}

By default, numbers and symbols are listed before letters. ^{Note 3}

This is the same result as setting the orderby flag to SORT_REGULAR or SORT_STRING ^{Note 4}

• 1
• 2
• @
• A
• B

For example:

<?php $alphabetise = alphabetise($page->children()->listed()->sortby('title'), array('key' => 'title', 'orderby'=>SORT_REGULAR));?>

To list letters before numbers, set the orderby flag to SORT_NUMERIC ^{Note 5}

• A
• B
• @
• 1
• 2

For example:

<?php $alphabetise = alphabetise($page->children()->listed()->sortby('title'), array('key' => 'title', 'orderby'=>SORT_NUMERIC));?>

Additional Notes

¹ The explode function used for array parsing uses the tilde character ~ as the separator value. If this character appears in one of the key values, especially at the beginning of a string, you could run into sorting problems. You can manually change the separator value if required.

² The value of the orderby flag is not a string.

³ PHP 8.2 changed the way the ksort function behaves when using the SORT_REGULAR flag. In previous versions of PHP, the SORT_REGULAR flag listed numeric characters after alphabetical characters. It now arranges numeric characters before alphabetical characters, the same as the SORT_STRING and SORT_NATURAL flags.

⁴ This plugin uses the PHP ksort function, so other sorting type parameters might work, but have not been tested.

⁵ Using the SORT_NUMERIC flag may result in unexpected results if any of your key values consist of single characters.

Release Notes

0.1.3

• Added check for duplicate key values.
• Modified handling of single character key field text.
• Changed plugin namespace from shoesforindustry to splorp to match fork.
• Updated documentation.

0.1.2

• Added field to composer.json for link in the Kirby Panel.

0.1.1

• Additional fixes for Kirby 3 compatibility.

0.1.0

• Renamed alphabetise.php to index.php for Kirby 3 compatibility.
• Renamed package.json to composer.json
• Updated documentation.

0.0.9

• Added orderby key for alternative sort order.

0.0.8

• Fixed Array to string conversion error.

0.0.7

• Fixed a small bug introduced in the 0.0.6 update.

0.0.6

• Fixed bug when using only a single character of text for a key field.
• Updated documentation to remove workaround.

0.0.5

• Discovered bug when using only a single character of text for a key field.
• Updated documentation with explanation and possible workaround.

0.0.4

• Bug fix for spaces in explode key, now '~' instead of space ' '
• Updated page code with a pre-sort 'sortby('title')'
• Updated documentation and examples.

0.0.3

• Updated documentation.

0.0.2

• Added error handling code.
• Updated documentation.

0.0.1

• Initial release.

Authors

Russ Baldwin
shoesforindustry.net

Grant Hutchinson
splorp.com