sylvainjule/imageboxes

Add illustrations to Kirby's checkboxes

2.0.1 2024-05-05 13:44 UTC

Requires

• getkirby/composer-installer: ^1.1

MIT

• Sylvain Julé

README

Add illustrations to checkboxes.

Overview

This plugin is completely free and published under the MIT license. However, if you are using it in a commercial project and want to help me keep up with maintenance, please consider making a donation of your choice.

• 1. Installation
• 2. Setup
  • 2.1. Hardcoded options
  • 2.2. Dynamic options
• 3. Global options
• 4. Per-field options
• 5. License

1. Installation

Kirby 3: Up to 1.0.6. Kirby 4: 2.0.0+

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

Alternatively, you can install it with composer: composer require sylvainjule/imageboxes

2. Setup

The field is best used with the columns option set.

2.1. Hardcoded options

If the field's options are hardcoded, images need to be placed in the assets/images folder of your installation.

The image value must be a filename, the field will automatically prefix it with the correct path.

myimageboxes:
  label: Categories
  type: imageboxes
  columns: 3
  options:
    bears:
      text: Brown bears
      image: bears.jpg
    bisons:
      text: Bisons
      image: bisons.jpg
    marmots:
      text: Marmots
      image: marmots.jpg

2.2. Dynamic options

The field is compatible with both query and api fetch. You need to explicitely set the result text, stored value and image url.

The image value must return an absolute url.

myimageboxes:
  label: Categories
  type: imageboxes
  columns: 3
  options: query
  query:
    fetch: page.images
    text: "{{ file.filename }}"
    value: "{{ file.id }}"
    image: "{{ file.resize(512).url }}"

Notice the {{ file.resize(512).url }} instead of {{ file.url }}. Two reasons for this:

• Using a thumb url will prevent loading unnecessarily large images.
• 512 is the default value of the Files field's thumbs. Therefore it is likely that the thumb will have already been created.

I recommend using a resize number already used by the panel (128, 256, 512, 768, 1024).

3. Global options

3.1. baseUrl

If you want the images to be queried from a different location than the assets/images folder, you can set the baseUrl option in your config.php file to whatever folder you'd like. For example:

'sylvainjule.imageboxes.baseUrl' => '{{ kirby.url("assets") }}/my-custom-folder',

4. Per-field options

4.1. ratio

The ratio of the image container, to be adjusted depending on your images. Default is 1/1.

myimageboxes:
  type: imageboxes
  ratio: 1/1

4.2. fit

Defines how the image should fit within its container, either contain or cover. Default is cover.

myimageboxes:
  type: imageboxes
  fit: cover

4.3. back

Defines the background behind transparent / contained images. Accepts any CSS-valid property for the background property. Default is false.

myimageboxes:
  type: imageboxes
  back: white # or '#fefefe', or 'rgb(255, 0, 255)', etc.

4.4. mobile

By default, images are not displayed when the panel switches to its mobile view. Not recommended, but if you want to override this, set the option to true.

myimageboxes:
  type: imageboxes
  mobile: false

5. License

MIT