Umbraco and Sass loops: a flexible approach to colour theming

As a front-end developer, I’m often required to work with various brand colour schemes and guidelines for clients. In this article I’d like to share an example of how I would approach colour customisation and personalisation using Umbraco.

Umbraco’s Color Picker Data Type makes it really easy for us to achieve this, whether you are looking to add various colour options to a content block or component, or whether you want to apply a global colour theme to your website.

Here are the steps we will take to achieve this:

  • Add the Umbraco color picker property editor to a Document Type
  • Use Sass to apply the colours to a content block, based on the user selection in Umbraco

Adding the color picker

We can add a colour picker to any Document Type. If I was working on a client project, I would create a content block, and add a colour picker to change the background of that specific block. That is a typical use case for me, however this approach is very flexible and can be used in many ways to suit your needs. For the purposes of this article, let’s add it to a content block.

In the Umbraco backoffice, go to Settings and create a Document Type without a template. In this Document Type, click on add property, and we will call this property ‘Background colour’, then click on Add editor and we will add the Color Picker.

There is a toggle in the Color Picker settings which says Include labels. We have two options here; we can either turn this on and give each colour a label, in which case we will be able to access the hex value and the label in our View. Or we can leave this turned off and only receive the hex value. If we choose to have no labels, we may have to create a Colour Helper method in order to apply our class names for colour customisation. We will talk about that a little later on in the article, but for now, let’s switch this toggle on to include the labels.

Capture.JPG

Add a few hex values, along with labels to describe them and any other properties you would like for your content block, and then save it. Normally I would then use ModelsBuilder in Visual Studio to generate my models.

In the content area of the site, when we add our block to a page, we should now see a Background colour property where we can select a background colour from the swatch of colours we have just set up in the Document Type. This is going to be our content block background colour.

The View

When we created our Document Type, we had the option to add a label as well as setting the hex value. Adding the label is optional, and in this example we will use the label we’ve set in the CMS as our class name.

In the View we want to pull through the label value from the Background colour property and set it as a variable:

var bgColour = (Model.BackgroundColour != null) ? Model.BackgroundColour.Label?.ToLower() : String.Empty;

This will take the label value, if a colour has been set, and make it lower case. We added the labels in the CMS with capital letters for better presentation in the backoffice, but for our CSS class names, we'd rather have them lower case. We can then apply this as a class in our markup:


<section class="contentBlock @bgColour"></section>

Adding a Colour Helper

As discussed earlier, in some cases you may want the label to be different to the class name itself. If that’s the case, you can add a Colour Helper. In your project, navigate to the Core/Helpers folder and create a new file called ColourHelper.cs. Add the following code:

namespace Project.Core.helpers
{
    public static class ColourHelper
    {
        public static string GetColourBasedOnHex(string hexValue, string defaultColour = "grey")
        {
            switch (hexValue)
            {
                case "000000":
                    return "black";
                case "ffffff":
                    return "white";
                case "d5d5d5":
                    return "grey";
                default:
                    return defaultColour;
            }
        }
    }
}

To use this in our View we can then do the following:

var bgColour = Model.BackgroundColour != null ? 
        ColourHelper.GetColourBasedOnHex(Model.BackgroundColour.ToString()) : string.Empty; 

Whichever way you choose to do it, we now have a section with a colour class (“grey”, “black”, or “white”) applied to it, which is controlled from the CMS. The next step is to use a Sass each loop to apply this background colour to the section.

Using an Each loop in Sass

The @each rule in Sass is usually written like so: @each <variable> in <expression> { ... }, where the expression returns a list. The code examples shown below are taken from the Sass documentation.

$list: 10px, 20px, 30px;

@each $size in $list {
  .icon-#{$size} {
    font-size: $size;
   }
}

@each also supports destructuring and mapping:

$icons:
  "eye" "\f112" 12px,
  "start" "\f12e" 16px,
  "stop" "\f12f" 10px;

@each $name, $glyph, $size in $icons {
  .icon-#{$name}:before {
    display: inline-block;
    font-family: "Icon Font";
    content: $glyph;
    font-size: $size;
  }
}

$icons: ("eye": "\f112", "start": "\f12e", "stop": "\f12f");

@each $name, $glyph in $icons {
  .icon-#{$name}:before {
    display: inline-block;
    font-family: "Icon Font";
    content: $glyph;
  }
}

Now onto our own code! We have a few different background options we could use for our block, which we’ve set up in our Document Type. We need our Sass loop to take into account both the class name and the hex value, so for this we will use mapping.

$background-colours: (
  black: #000000,
  white: #ffffff
  grey: #d5d5d5
);

.contentBlock {
    @each $class, $colour in $background-colours {
        &.#{$class} {
          background: $colour;
        }
    }
}

Using this Sass each loop means that we don't have to write out the individual code for each colour, which would normally look like this:

.contentBlock {
  &.white {
    background: #ffffff;
  }
  &.grey {
    background: #d5d5d5;
  }
  &.black {
    background: #000000;
  }
}

This might not seem like much, but the @each loop will save you a lot of code!

Now if we ever want to add any more colours to our background colour options, we just need to add our class name and hex value to the $background-colours variable in Sass, and then add the same values in our Document Type for the user to be able to select it from Umbraco.

And that’s it! I hope this helps to create a more flexible and customisable experience for Umbraco users.

Lynne Finnigan

Lynne is on Twitter as