Skip to content

Usage (Version 2)

Jump to bottom
Jake Jones edited this page Jan 8, 2020 · 9 revisions

The Basics

Defining a Single Palette

Defining a single palette in the Configurable Color Picker is extremely simple. First, you should create ColorPalette.config in the web root.

A single palette with the desired number of colors can then be defined as per the example here:

<?xml version="1.0" encoding="utf-8"?>
<colorPalettes>
  <colorPalette>
    <maxColumns>3</maxColumns>
    <showClearButton>true</showClearButton>
    <colors>
      <color id="1">
        <value>#fff</value>
        <name>White</name>
      </color>
      <color id="2">
        <value>#ff0000</value>
        <name>Red</name>
      </color>
      <color id="3">
        <value>#0000ff</value>
        <name>Blue</name>
      </color>
    </colors>
  </colorPalette>
</colorPalettes>

A few things warrant further explanation here:

  1. maxColumns is optional (defaults to 4) and represents the maximum width of the color picker in terms of columns.
  2. showClearButton is optional (defaults to true) and indicates that the editor should be able to clear the selected color via a button.
  3. The color name is optional and is used as a tooltip in the UI (otherwise the value is shown).

Usage

Utilizing this color palette is then as simple decorating it with the ColorPickerAttribute (DoubleJay.Epi.ConfigurableColorPicker.Infrastructure):

[ColorPicker]
public virtual IColor Color { get; set; }

As per the snippet above this gives an IColor (DoubleJay.Epi.ConfigurableColorPicker.Models) which contains the ID, Name and Value.

Setting a default value is also straight-forward:

public override void SetDefaultValues(ContentType contentType)
{
    base.SetDefaultValues(contentType);
    Color = new Color(3);
}

Troubleshooting

Should a palette not appear in the UI or be missing a color please refer to the log files, the Configurable Color Picker includes extensive logging especially with regards to invalid configuration structure and issues like duplicate color IDs.

Naming and Using a Specific Palette

Configuration

Naming palettes was introduced in Configurable Color Picker v2 and allows multiple palettes to be defined and utilized as required. For example, specific page or block types may require a different color palette to that used throughout the rest of the site.

This is easily achieved in the configuration:

<?xml version="1.0" encoding="utf-8"?>
<colorPalettes>
  <colorPalette>
    <name>Standard</name>
    <colors>
      <color id="1">
        <value>#ff00ff</value>
        <name>Magenta</name>
      </color>
      <color id="2">
        <value>#ffff00</value>
        <name>Yellow</name>
      </color>
    </colors>
  </colorPalette>
  <colorPalette>
    <name>Editorial</name>
    <maxColumns>2</maxColumns>
    <showClearButton>false</showClearButton>
    <colors>
      <color id="1">
        <value>#00ff00</value>
        <name>Lime Green</name>
      </color>
      <color id="2">
        <value>#00ffff</value>
        <name>Cyan</name>
      </color>
      <color id="3">
        <value>#000</value>
        <name>Black</name>
      </color>
    </colors>
  </colorPalette>
</colorPalettes>

Usage

Specifying which palette to use for a given property is as simple as passing in the name to the ColorPickerAttribute. To use the ‘Standard’ palette defined in the example configuration above you’d do the following:

[ColorPicker("Standard")]
public virtual IColor Color { get; set; }

Configuring the Palette Based on the Site

Configuration

Because the Configurable Color Picker stores the selected color’s ID and not it’s HEX value it supports utilizing a different palette per website in a multi-tenant setup.

Editors can select from the appropriate palette based on the site they’re editing, should a page or block be moved between sites the palette will change and the selected color will be switch out accordingly (based on its ID).

This is achievable in configuration by specifying the hosts:

<?xml version="1.0" encoding="utf-8"?>
<colorPalettes>
  <colorPalette>
    <maxColumns>3</maxColumns>
    <showClearButton>true</showClearButton>
    <hosts>
      <host>alloy-dev.local</host>
      <host>alloy-prod.com</host>
    </hosts>
    <colors>
      <color id="1">
        <value>#fff</value>
        <name>White</name>
      </color>
      <color id="2">
        <value>#ff0000</value>
        <name>Red</name>
      </color>
      <color id="3">
        <value>#0000ff</value>
        <name>Blue</name>
      </color>
    </colors>
  </colorPalette>
  <colorPalette>
    <hosts>
      <host>alloy-micro-dev.local</host>
      <host>alloy-micro-prod.com</host>
    </hosts>
    <colors>
      <color id="1">
        <value>#000</value>
        <name>Black</name>
      </color>
      <color id="2">
        <value>#00ffff</value>
        <name>Cyan</name>
      </color>
      <color id="3">
        <value>#ffff00</value>
        <name>Yellow</name>
      </color>
    </colors>
  </colorPalette>
</colorPalettes>

In the example above if the editor edits alloy-prod.com they get the first palette but editing alloy-micro-prod.com gives the second palette. Should the content the palette is used on move between the sites the color would also update, for example, if color number 3 was selected this would change from blue to yellow or vice-versa.

Considerations

When utilizing this functionality ideally the palettes would have the same number of colors, however, this is not mandated. If the selected color’s ID is not present in a palette then null is returned and a warning is written to the log, be sure to handle this null in code if this is a requirement.

Assigning a Fallback Palette

Configuration

Fallbacks are useful when you want to want to re-use a palette with only a few changes (e.g. a few color substitutions or removing the button allowing editors to clear their color selection).

Fallbacks were overhauled in version 2 of the Configurable Color Picker to remove the requirement of automatic fallbacks to the default palette. This means that as of version 2 it’s necessary to assign IDs to the color palettes so a specific palette can be referenced. An example of this configuration is shown here:

<?xml version="1.0" encoding="utf-8"?>
<colorPalettes>
  <colorPalette id="1">
    <colors>
      <color id="1">
        <value>#fff</value>
        <name>White</name>
      </color>
      <color id="2">
        <value>#ff0000</value>
        <name>Red</name>
      </color>
      <color id="3">
        <value>#0000ff</value>
        <name>Blue</name>
      </color>
    </colors>
  </colorPalette>
  <colorPalette id="2" fallback="1">
    <name>Magenta Alternative</name>
    <colors>
      <color id="3">
        <value>#ff00ff</value>
        <name>Magenta</name>
      </color>
    </colors>
  </colorPalette>
  <colorPalette id="3" fallback="1">
    <name>Non-Clearable Alternative</name>
    <showClearButton>false</showClearButton>
  </colorPalette>
</colorPalettes>

This defines a default palette (with the ID 1) and then 2 alternative named palettes. Both these palettes fallback to using the default palette but with alterations, the ‘Magenta Alternative’ switches out the color with ID 3 to magenta, whilst the ‘Non-Clearable Alternative’ removes the button which clears the color selection.

Considerations

When fallbacks are used name and host configurations are not applied automatically, which means that these should be defined for each palette individually (if required) regardless of fallbacks.

Usage

Clone this wiki locally