sylvainjule/color-palette

A color palette to pick colors from for Kirby

1.0.4 2020-04-11 10:05 UTC

Requires

• getkirby/composer-installer: ^1.1

MIT

• Sylvain Julé

README

A color palette displayed in the panel, helping you pick predefined colors / palettes.

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 or purchasing your license(s) through my affiliate link.

• 1. Installation
• 2. Setup
• 3. Configuration
• 4. Extract palette from an image
• 5. Template usage
• 6. License
• 7. Credits

1. Installation

Download and copy this repository to /site/plugins/color-palette

Alternatively, you can install it with composer: composer require sylvainjule/color-palette

2. Setup

A basic setup looks like this:

palette:
  label: Pick a color
  type: color-palette
  options:
    - '#135fdc'
    - '#f6917e'
    - '#6a96e4'
    - ...

Note that you can fill it with any CSS-valid color:

- '#ffffff'
- rgba(255, 255, 255, 0.5)
- rgb(255, 255, 255)
- white

3. Configuration

3.1. options (required)

The plugin accepts both an array or a structured object.

• Simple colors

palette:
  type: color-palette
  options:
    - '#135fdc'
    - '#f6917e'
    - '#6a96e4'
    - ...

• Structured color themes

The field will use the first color of the object as the background-color.

palette:
  type: color-palette
  options:
    blue:
      background: '#135fdc'
      border: '#0438c7'
      text: white
    orange:
      background: '#f6917e'
      border: '#ef6a57'
      text: white
    ...

You can add tooltips to structured colors: any color with the tooltip key will show a tooltip on hover.

...
  options:
    blue:
      background: '#135fdc'
      tooltip: This is a tooltip
    ...

• Dynamic options

You can set dynamic options / query your options from a different field. Just make sure the value returns a CSS-valid color.

For example with a structure field:

palette:
  type: color-palette
  options: query
  query:
    fetch: page.mycolors.toStructure
    value: "{{ structureItem.color }}"

...

mycolors:
  type: structure
  fields:
    color:
      type: text

3.2. display

The display style of the color blocks, to pick from single or duo . Default is single.

If the selected style is duo and the options are structured color themes, the field will use the first color of the object as the left color, and the second as the right color.

palette:
  type: color-palette
  display: single

3.3. size

The size of the color blocks, to pick from small, medium or large. Default is medium.

palette:
  type: color-palette
  size: medium

3.4. unselect

If set to true, selected colors can be unselected. Default is false.

palette:
  type: color-palette
  unselect: false

3.5. default

The default value to be used if the field has no set value. Will be ignored if it doesn't match an option. Default is false.

#simple colors
palette:
  type: color-palette
  default: '#135fdc'
  options:
    - '#135fdc'
    - '#f6917e'

# structured colors
palette:
  type: color-palette
  default: blue
  options:
    blue:
      background: '#135fdc'
      border: '#0438c7'
    orange:
      background: '#f6917e'
      border: '#ef6a57'

4. Extract palette from an image

4.1. Select manually which image to extract colors from

You can extract a color palette from a page's image file by activating the extractor option. It will override the manual options, if specified. Default is false.

palette:
  type: color-palette
  extractor: true
  # no need for options anymore

You can restrict the choices to a specific file template with the template option:

palette:
  type: color-palette
  extractor: true
  template: cover

4.2. Automatically extract colors when an image matches a template

Alternatively, you can make use of the autotemplate option (do not add the above extractor option in this case).

If the page has at least 1 image matching the given template (if 2+ are found, the field will use the first one), options will automatically be extracted from it on load.

Note that there is no realtime-sync, the page needs to be reloaded in order for the plugin to detect a newly added image. The best way of achieving this without having to manually refresh the page is to place this field and the files section under two different tabs.

palette:
  type: color-palette
  autotemplate: cover
  # no need for options anymore

4.3. Limit

In both cases, the maximum number of extracted colors can be set with the limit option. Default is 10.

palette:
  type: color-palette
  extractor: true
  limit: 10

5. Template usage

5.1. If options is an array of simple colors

The field will only store the selected color.

$selected = $page->palette();   #(Field object)
$selected = $selected->value(); #(string)

5.2. If options is a structured color object

The field will need to be decoded with the yaml method. For example, if your options look like this:

options:
  blue:
    background: '#135fdc'
    border: '#0438c7'

Here's how to get the selected color:

$palette    = $page->palette()->yaml();
$background = $palette['background']; #(string)
$border     = $palette['border']; #(string)

Note that in this case, the plugin automatically adds the key of the selected color, in case you'd want it to deal with custom classes, etc.

$border     = $palette['key']; #(string)

5.3. If the palette has been extracted from an image

Both the selected color and the extracted palette are stored. The value of the field is an array you'll need to decode with the yaml method:

$palette  = $page->palette()->yaml();
$selected = $palette[0]; #selected color (string)
$palette  = $palette[1]; #extracted palette (array)

6. License

MIT

7. Credits

• K2 version: Color list by @Thiousi