README

The Relationship field allows you to select and sort multiple items from a list.

The field was originally created for Kirby 2, where a native multiselect field was not available at the time. With Kirby 3, a built in multiselect field was added, and this field was not really needed anymore. But some people liked the different ui this field provided so it was updated to support Kirby 3.

This plugin is free to use. But if you find it helpful, feel free to buy me a coffee ☕️ or purchase your Kirby license(s) through my affiliate link.

Requirements

Kirby 3

Still using Kirby 2? Please use the version for Kirby 2 of this plugin.

Installation

Download and copy this repository to /site/plugins/relationship

Alternatively, you can install it with composer: composer require olach/relationship

Usage

Define a list of options in the field settings. Either manually or using the powerful Query Language.

The data is saved as a comma separated string, which means that this field is interchangeable with the regular Multiselect field.

Example with predefined options

Blueprint

countries:
  label: Countries
  type: relationship
  options:
    sweden: Sweden
    norway: Norway
    denmark: Denmark
    finland: Finland
    iceland: Iceland
    germany: Germany
    france: France
    spain: Spain
    portugal: Portugal

Template

<ul>
  <?php foreach ($page->countries()->split() as $country): ?>
  <li><?= $country ?></li>
  <?php endforeach ?>
</ul>

Example with related pages

Blueprint

related:
  label: Related articles
  type: relationship
  options: query
  query: page.siblings

Template

<h2>Related articles</h2>
<ul>
  <?php foreach ($page->related()->toPages(',') as $related): ?>
  <li>
    <a href="<?= $related->url() ?>">
      <?= $related->title() ?>
    </a>
  </li>
  <?php endforeach ?>
</ul>

Features

Search:

To enable search, add search: true to the field settings in your blueprint.

related:
  label: Related articles
  type: relationship
  options: query
  query: page.siblings
  search: true

Min and max items:

You can control the minimum number of required items and the maximum number of allowed items. Don't forget to add a help text to inform the editor about the requirements.

related:
  label: Related articles
  type: relationship
  options: query
  query: page.siblings
  search: true
  min: 3
  max: 6
  help: Select from 3 up to 6 articles.

Counter indicator

A handy indicator of the current amount of selected items is displayed in the upper right corner. This indicator can be disabled by setting the value of option counter to false.

related:
  label: Related articles
  type: relationship
  options: query
  query: page.siblings
  counter: false

Keyboard navigation:

The field is keyboard accessible. Press tab and shift + tab to give focus to the lists. Within a list, use the arrow keys to navigate and press space to select/deselect an item. In the sortable list, you can sort the items by selecting an item with space and then move the item using the arrow keys.

License

MIT