Skip to content

Usage (Version 1)

Jump to bottom
Jake Jones edited this page Jan 8, 2020 · 6 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).

A palette with no host or fallback defined (as shown in the example above) is considered the default and is used as the final fallback for all other palettes. See the Assigning a Fallback Palette section for more information.

Usage

Utilizing this color palette is then as simple decorating it with the ColorPicker UIHint (DoubleJay.Epi.ConfigurableColorPicker) and specifying the PropertyPaletteColor (also DoubleJay.Epi.ConfigurableColorPicker) as the backing type.

[UIHint(ColorPickerUIHint.ColorPicker)]
[BackingType(typeof(PropertyPaletteColor))]
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.

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 host="alloy-prod.com">
    <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>
  <colorPalette host="alloy-micro-prod.com">
    <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 between sites unchanged or make limited modifications (e.g. a few color substitutions or removing the button allowing editors to clear their color selection).

The following example shows how fallbacks work:

<?xml version="1.0" encoding="utf-8"?>
<colorPalettes>
  <colorPalette>
    <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 host="alloy-micro-prod.com">
    <colors>
      <color id="3">
        <value>#ff00ff</value>
        <name>Magenta</name>
      </color>
    </colors>
  </colorPalette>
  <colorPalette host="alloy-prod.com" fallback="alloy-micro-prod.com">
    <showClearButton>false</showClearButton>
    <colors>
      <color id="1">
        <value>#ffff00</value>
        <name>Yellow</name>
      </color>
    </colors>
  </colorPalette>
</colorPalettes>

This defines a default palette and then 2 additional palettes for specific host names. Each palette ultimately fallbacks to the default palette which means our fallback order for this example looks like this:

alloy-prod.com palette → alloy-micro-prod.com palette → default palette

This means that the palette for alloy-micro-prod.com shares the white and red colors with the default palette only replacing the blue (ID 3). Similarly, the palette for alloy-prod.com has the red (ID 2) from the default palette and magenta (ID 3) from the alloy-prod.com palette. It additionally removes the button which clears the color selection.

Considerations

As noted, all palettes ultimately fallback to the default which therefore dictates the minimum number of colors required.

Usage

Clone this wiki locally