README

Choices offers methods to resolve selections stored by select, multiselect or checkboxes fields back to their human-readable values. It also gives access to the full list of options defined in the blueprint, either written statically or loaded via query or api settings.

Introduction

Choices’ primary usecase is outputting selections and field options on the frontend. For instance, you can use it to show categories and tags or to create classes and data attributes from a selection. It can also be used to resolve selections in info or help texts inside of panel sections.

Choices is used as shared term for both selection and option lists.

The plugin creates a collection of all choices and allows you to evaluate, manipulate and convert them on the fly.

Field method

$field->toChoices($all, $context)

• all: bool
  Whether to include all defined choices or not. Defaults to false.
• context: string
  The name of the parent, if the field is nested. Defaults to null.

Given a field with options, this method retrieves all choices made by the editors or – if the all parameter is set – of all options defined for this field.

In case of nested fields, e. g. when used inside a structure field, the name of the parent field must be passed as context in order to retrieve the choices.

Choices extends the default Kirby Collection class and thus offers all methods known from other Kirby object like first(), last(), shuffle(), sort() and the like.

Basic examples

Given a select field with fruits, either return the selected or all available options in human readable format.

Field

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

Content

Title: Choices example

-----

Fruits: apple, pear

Output the selected options

// Return selected fruits: "Apple Pear"
<?php foreach ($page->fruits()->toChoices() as $fruit): ?>
    <?= $fruit ?>
<?php endforeach; ?>

Output all available options

// Return all fruit options: "Apple Pear Banana"
<?php foreach ($page->fruits()->toChoices(all: true) as $fruit): ?>
    <?= $fruit ?>
<?php endforeach; ?>

Out the selected options as comma-separated list

// Return selected fruits: "Apple, Pear"
<?= $pages->fruits()->toChoices()->join() ?>

Tip

See the manipulation guides to learn how to use Kirby’s string methods on all choices before output. There are also methods to evaluate the existence or non-existence of a choice and further options to convert content to another type – for instance, switching between text and value output.

Installation

By default, plugins in Kirby reside in a special folder located at /site/plugins. Each plugin is installed in its proprietary subfolder. This installation can be handled in four different ways: you can either install them manually or manage them using Kirby CLI, Git submodules or Composer. You can install Choices either way and should choose the method suiting your project best.

Please note that all examples given here assume you are using the default plugin root. If you changed your plugin root, e. g. with a custom folder setup, you’ll also have to adjust the paths given in this guide. For further information on how to manage plugins, please read the official Kirby plugin introduction.

Download

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

Kirby CLI

kirby plugin:install hananils/kirby-choices

Git submodule

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

Composer

composer require hananils/kirby-choices

Documentation

Where possible, files contain inline annotations. For extended documentation, please visit our dedicated plugin site at kirby.hananils.de/​plugins/​choices.

Guides

• Evaluation
• Manipulation
• Conversion

Reference

• Field Methods

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.