Building a property editor for Umbraco Belle

When I was working at the Umbraco HQ I wrote a blog tutorial on creating a property editor which was a RGBA colour picker. In this tutorial I will be recreating the same property editor for Umbraco Belle.

So the first thing first is to create a folder called RGBAEditor in App_Plugins in an Umbraco Belle installation. This is where we store the HTML, JS and package manifest file for our property editor.

{
propertyEditors: [
{
id: "B2FE9CFE-50FC-42A5-9DFE-35DE84953C67",
name: "(CWS) RGBA Colour Picker",
editor: {
view: "~/App_Plugins/RGBAEditor/rgba-editor.html"
}
}
]
,
javascript: [
'~/App_Plugins/RGBAEditor/rgba.controller.js'
]
}

In this JSON, we give our property a unique GUID, a friendly name for our property editor so we can choose it from the back office and then we define the HTML Angular JS view for our property editor. In this case it's rgba-editor.html. Finally we define the Javascript needed to load for this property editor which in this case is our AngularJS controller file - rgba.controller.js

Next we need to add our HTML for our property editor, in this case it will contain three sliders and an element to show a live preview of the RGBA colour. So in rgba-editor.html file we need the following.

<div ng-controller="CWS.RGBAController">
<div class="row">
<!-- SLIDERS -->
<div class="sliders span8">
<!-- RED -->
<div class="control-group">
<label class="control-label" for="rgba-red">Red</label>
<div class="controls">
<input type="text" name="rgba-red" ng-model="renderModel.red" class="slider red" data-slider-min="0" data-slider-max="255" data-slider-step="1" data-slider-value="255" data-slider-orientation="horizontal" data-slider-selection="after" data-slider-tooltip="show"/>
</div>
</div>

<!-- GREEN -->
<div class="control-group">
<label class="control-label" for="rgba-green">Green</label>
<div class="controls">
<input type="text" name="rgba-green" ng-model="renderModel.green" class="slider green" data-slider-min="0" data-slider-max="255" data-slider-step="1" data-slider-value="0" data-slider-orientation="horizontal" data-slider-selection="after" data-slider-tooltip="show"/>
</div>
</div>

<!-- BLUE -->
<div class="control-group">
<label class="control-label" for="rgba-blue">Blue</label>
<div class="controls">
<input type="text" name="rgba-blue" ng-model="renderModel.blue" class="slider blue" data-slider-min="0" data-slider-max="255" data-slider-step="1" data-slider-value="0" data-slider-orientation="horizontal" data-slider-selection="after" data-slider-tooltip="show"/>
</div>
</div>

<!-- ALPHA -->
<div class="control-group">
<label class="control-label" for="rgba-alpha">Alpha (%)</label>
<div class="controls">
<input type="text" name="rgba-alpha" ng-model="renderModel.alpha" class="slider alpha" data-slider-min="0" data-slider-max="100" data-slider-step="1" data-slider-value="100" data-slider-orientation="horizontal" data-slider-selection="after" data-slider-tooltip="show"/>
</div>
</div>
</div>

<!-- PREVIEW -->
<div class="preview span4">
<!-- This will show a live preview of the RGBA colour based on jQuery UI sliders below -->
<div id="rgba-preview-{{model.alias }}"><span ng-style="{background: preview}"></span></div>
{{ renderModel.red }} {{ renderModel.green }} {{ renderModel.blue }} {{ renderModel.alpha }}
</div>
</div>
<hr/>
<h6>Debug JSON</h6>
{{ model | json }}
</div>

The code is heavily commented above and hopefully should make sense, but I will go over some key points in it.

First we define our controller CWS.RGBAController which is the same as the ng-controller attribute in our view. Next key point is the assetsService which the Umbraco guys have made that allows us to load in external Javascript dependencies. In this case I am loading in the Eyecon.ro Bootstrap Slider library so that I can use it. Once it's loaded we can work with it inside the .then function.

In here we initiate our sliders and then have a function for every time one of the sliders is updated we update our scope values, the most important being $scope.model.value as this is what will be saved back into Umbraco when the user clicks save on the document and in addition we update the preview as well on the scope so that we can allow the colour preview to be updated in the HTML view. We store the RGBA value in Umbraco as a CSV string r,g,b,a.

The final part to this is to get the values when the property editor is initially loaded and set the sliders to those values, which we will need to do when we come back to the node when the values have been saved. We do this by doing a simple split of the values and then setting the sliders back to those values from the CSV string stored in Umbraco.

It's as easy as that to create a property editor for Umbraco Belle, no Visual Studio needed. No compiling down to DLLs and writing C# code. This is so easy to do that your front-end developer can start writing property editors for Umbraco.

Which is fantastic news

Here's to a bright and happy future with Umbraco Belle.