List Methods is a plugin for Kirby 3 providing methods to generate comma-separated list from collections like pages, users or files. It allows for custom field selection for the list value, optional conjunctions for the last item (e. g. "and") and custom links for each item that can be defined using Kirby's query language (e. g. {{page.url}}). It also provides specific methods to list numeric values like years, shortening ranges for better readability.
Download and copy this repository to /site/plugins/list-methods.
git submodule add https://github.com/hananils/kirby-list-methods.git site/plugins/list-methods
composer require hananils/kirby-list-methods
There are different options to create lists from users, pages or files collections:
Creates a list separated all items with a comma:
// using the username
$users->toList();
// using the page title
$pages->toList();
// using the filename
$files->toList();Creates a list of years:
// numeric list, returns "2010–2012, 2022" for "2010, 2011, 2012, 2022"
$page->years()->toNumericList();
// numeric list with "since", return "since 2020" for "2020, 2021, 2022"
$page->years()->toNumericList(true);Creates a list separated all items with a comma:
// using the custom method `nickname`
$users->toList('nickname');
// using the field category
$pages->toList('category');
// with numeric values
$pages->toNumericList('date');Creates a list separated all items with a comma but the last which is connected with a cunjunction:
// creates, a, list, with, commas and conjunction
$pages->toList('title', true)
// creates, a, list, with, commas & conjunction
$pages->toList('title', '&')The default conjunction and is provided in English or German depending on your language settings.
Creates a list linking to a custom destination:
// link everything to the same URL
$pages->toList('title', true, 'https://example.com');
// link all pages to their own URL
$pages->toList('title', true, '{{page.url}}');
// link all pages to a custom URL
$pages->toList('title', true, 'my-custom-path/{{page.category}}');
// link all pages to a custom URL with numeric values
$pages->toNumericList('date', true, 'my-year-overview/{{page.date.toDate('Y')}}');You can use Kirby's template syntax with query language to fetch any information from the current context, e. g. the current $user, $page or $file object. The $kirby and $site objects are also available.
When dealing with a single page or user, there are methods to generate lists from content field:
// Given the fields name and job, creates "Jane Doe, astrophysicist"
echo $user->asList(['name', 'job']);
// Given the fields start and end, creates "2020–2023"
echo $page->asNumericList(['start', 'end']);Both methods, asList and asNumericList, support setting a custom conjunction via a secondary attribute:
// Given the fields name and job, creates "Jane Doe: astrophysicist"
echo $page->asList(['name', 'job'], ': ');The plugin also features a general, more simple collection method which is a shortcut the naturalList() helper and only allows for a custom conjunction:
// Create a Choices collection for instance, see https://github.com/hananils/kirby-choices
$choices = $page->categories()->toChoices();
// Convert all choices to a comma-separated list
echo $choices->toList();
// Convert all choices to a comma-separated list with the default conjunction
echo $choices->toList(true);
// Convert all choices to a comma-separated list with a custom conjunction
echo $choices->toList('&');If you'd like to create a list outside of the Kirby objects, from an array for instance, you can use the naturalList() helper. It accepts a flat array and a conjunction, there is no custom key selection or template syntax support:
$data = ['this', 'that'];
// this, that
naturalList($data);
// this and that
naturalList($data, true);
// this & that
naturalList($data, '&');If you are handling numeric values, you can use the numericList() helper:
$data = [2019, 2020, 2021, 2022];
// 2019-2022
numericList($data);
// since 2022
numericList($data, true);This plugin is provided freely under the MIT license by hana+nils · Büro für Gestaltung. We create visual designs for digital and analog media.