README

This module allows you to manage and use colour palettes in your SilverStripe project.

Installation

To install the module, use Composer:

composer require toastnz/colourpalettes

Adding and editing colours

Colours can be managed in the CMS site config under 'Customisation' -> 'Colour Palettes'. Here you can add, edit and delete colours.

Colour palettes configuration

You can define default colours as well as colour groups in a yml config file. Default colours need to be hex codes without the #, contract colours are more customisable, and can be set to other variables, therefore a # is required if you want to use a hex code.

---
Name: colours
After: colourpalettes
---

Toast\ColourPalettes\Models\Colour:
  colour_groups:
    - Products
    - Buttons
  default_colours:
    - primary: null
    - secondary: null
    - white: 'ffffff'
    - black: '000000'
    - off-white: null
    - off-black: null
  contrast_colours:
    - on-dark: '#ffffff'
    - on-light: '#000000'

Adding colour groups will add a listbox to each colour added in the site config, allowing you to assign a colour to a single group or multiple groups.

Colours with a value will be locked and cannot be deleted or edited in the CMS. Groups are optional, but can be used to separate colours into various colour palette fields.

Contrast colours are the colours used when generating the css variables, on-dark will be used if the colour is set to dark, and on-light will be used if the colour is set to light. Makes senses right?

Adding Colour Palette Field to a Class

To add a colour palette field to a class, you can use the following code as an example:

use Toast\ColourPalettes\Models\ColourPalette;
use Toast\ColourPalettes\Fields\ColourPaletteField;

class YourClass extends DataObject
{
    private static $has_one = [
        'PrimaryColour' => Colour::class,
        'SecondaryColour' => Colour::class,
    ];

    public function updateCMSFields(FieldList $fields)
    {
        $fields->removeByName([
            'PrimaryColourID',
            'SecondaryColourID',
        ]);

        // Add the colour palette field to the class
        $fields->addFieldToTab('Root.Main', ColourPaletteField::create('PrimaryColour', 'Primary Colour'));

        // Optionally add a groups as an array to the field as the 3rd parameter
        $fields->addFieldToTab('Root.Main', ColourPaletteField::create('SecondaryColour', 'Secondary Colour', ['Products']));
    }
}

Template usage

To use the colours in your templates, you can use the following code as an example:

<!-- Add styles to the root -->
<style>
    :root {
        {$PrimaryColour.RootVars}
        {$SecondaryColour.RootVars}
    }
</style>

<!-- Add styles in a style tag scoped to this element -->
<div class="my-element">
    <p>lorem ipsum</p>

    <style>
        .my-element {
            {$PrimaryColour.CSSVars}
            {$SecondaryColour.CSSVars}
        }
    </style>
</div>

Using the colours in your CSS

The colours will automatically generate their own CSS variables based on the name you give them on the class. For example, if you have a colour field called 'PrimaryColour', the following CSS variables will be generated:

/* $PrimaryColour.RootVars */
:root {
    --primary-colour: #000000;
    --primary-colour-contrast: #ffffff;
}

/* PrimaryColour.CSSVars */
.my-element {
    --_primary-colour: #000000;
    --_primary-colour-contrast: #ffffff;
}

Helper functions

Sometimes you just want to know if the colour is light or dark:

<!-- Check if the colour is light or dark -->
<% if $PrimaryColour.IsLight %>
    <p>Primary colour is light</p>
<% end_if %>

<% if $PrimaryColour.IsDark %>
    <p>Primary colour is dark</p>
<% end_if %>