README

Choices is a plugin for Kirby 3 that provides methods to manage field options in the frontend. For any field – like select, multiselect or checkboxlist – that offers options settings in the blueprint, this plugin will load and return the readable text values for the keys stored in the content file. It works with static options directly set in the blueprint as well as dynamic ones loaded via query or api settings.

Note

Please check out the online documentation at kirby.hananils.de/plugins/choices for further information.

Example

Field

fields:
    fruits:
        label: Fruits
        type: select
        options:
            apple: Apple
            pear: Pear
            banana: Banana

Content

Title: Choices example

----

Fruits: apple, pear

Template

// Return selected fruits: "Apple Pear"
foreach ($page->fruits()->toChoices() as $fruit) {
    echo $fruit;
}

// Return selected fruits in flipped order: "Pear Apple"
foreach (
    $page
        ->fruits()
        ->toChoices()
        ->flip()
    as $fruit
) {
    echo $fruit;
}

Installation

Download

Download and copy this repository to /site/plugins/choices.

Git submodule

git submodule add https://github.com/hananils/kirby-choices.git site/plugins/choices

Composer

composer require hananils/kirby-choices

Field methods

toChoices()

Converts the field value to a Choices collection featuring the text values of the selected options:

$page->fruits()->toChoices();

If the method is passed an optional value of true, it will return text values for all options specified in the blueprint:

$page->fruits()->toChoices(true);

Choices collection

The Choices collection can be used to loop over all given options and return their values. It offers all methods known to the default Kirby collection like first(), last(), shuffle(), sort() and the like. Additionally, it provides three methods to simplify content output:

join($separator)

The join method concatenates all field value by a given separator.

• $separator: optional separator, uses , as default.

// Will return: Apple, Pear
$page
    ->fruits()
    ->toChoices()
    ->join();

If you want to have more control on how to join values – e. g. to have the last item joined by and – have a look at the List methods plugin.

missing($required)

The missing method compare the current field values with an array of required values and return the missing ones.

• $required: array of required values to be checked.

// Will return: Banana
$page
    ->fruits()
    ->toChoices()
    ->missing(['Apple', 'Banana']);

average($decimals)

The average method will calculate the average of all selected value, useful when handling numeric values.

• $decimals: the number of decimals to return.

License

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.