Custom Umbraco Property Editor Tutorial: Character Counts

Add character counts to Umbraco Text Fields

Today we will create a custom Umbraco Property Editor. This custom property editor adds a character counter to a Textstring or Textbox field. As you type, the character counter will countdown from the max value (we’ll assign that) to 0. Once it reaches 0, it will prevent any further entry. We found this to be most useful when setting up our SEO Metadata Document Type since it houses a few properties we needed to limit the character count on.

I’ve added a coloring convention to this blog post & I will try to follow it throughout my Umbraco related tutorials. Data Types will be in orange & Document Types will be in green.

You can skip all of this and just download the source on GitHub, if you like.

Before we go any further:

So let’s create our custom property editor.

Under the ”App_Plugins” folder create a new folder to house our new files. I created a folder called ”TextboxWithCharacterCount”. I find it easier to reuse the name for the folder, files, controllers, etc but it doesn’t matter what you call them!

You’ll need to create 3 files in the folder you just created:

  1. A Package Manifest
    • I named this ”package.manifest
  2. An HTML Template
    • I named this ”TextboxWithCharacterCount.html
  3. An Angular Controller
    • I named this ”TextboxWithCharacterCount.controller.js

The Package Manifest

The package manifest will be the first file you create. This file describes our plugin and provides instructions to Umbraco on what files to load. For more information on this step, see ”Creating a Property Editor“.

Important: The ”alias” property must be unique in your environment, and anyone who uses your code in their own Umbraco environment. For that reason, I prefix the alias with “Scylla.” creating an artificial namespace for all the plugins we create in-house. Prefix yours with something that makes it unique.

Not so Important: The ”name” property is the public-facing label Umbraco will use. This does not have to be unique and allows us to give our plugin a more friendly name.

Here is our package manifest:

The HTML Template & The Angular Controller

These two files work together to provide the interface. If you don’t know anything about Angular don’t fret - I’m pretty new to it too. What we are doing here is writing an Angular Controller, to interact with our HTML and provide back to Umbraco a value in the form of a JavaScript variable.

Again, looking at ”Creating a Property Editor” may give more insight. The page lists a couple of resources for learning Angular too:

Here is our HTML File:

And here is our Angular Controller:

Now we can put it to use!

Your file structure should look something like this:

File Structure for the Custom Umbraco Property Editor

Note that after uploading these files to your web server, you may need to recycle it for Umbraco to pick up the changes. I didn’t have to - a hard refresh in my browser window loaded our new property editor just fine.

Create Your Data Type

  1. Log into the Umbraco Back Office and load your “Developer” section.
  2. Right click “Data Types” to create a new one.
  3. Give it a name: “Textbox with Character Count”.
  4. Set the property editor to: “Textbox with Character Count”.
    • If you do not see your property editor I would recycle the site in IIS, if it’s still not available I would verify the 3 files have the exact code displayed above.
  5. Enter a Maximum value - this dictates how many characters you can type into the input field.
    • Not sure how many characters you want to limit it to? Don’t worry - this is used as a default value. It can be overridden later.

Add The Data Type to a Document Type

This is easy enough - find the document type you want to use this field in and add new property. For the type you’ll want to choose our new data type Textbox with Character Count.

Important: You can also update any existing property to use this field. Just remember that whatever data is stored in the field already will be truncated next time you go to edit it.

But we don’t always want the same character limit! How can we change this?

One step ahead of you! I’ve built in an override capability into the Angular Controller. It’s really easy to use, but it relies on a regular expression.

When we created the data type we set a default maximum value. Instead of creating various data types for everyone character amount we want, I’ve decided to read the description field and if a number is found, this number will override the default value. Pretty simple!

Here is an example. In the screenshot you’ll see two properties I’ve defined. They both use Textbox with Character Count, but one has the Description filled out.

Umbraco - Editing Properties

Now when I go to edit my content - the two properties will have different max values set.

Umbraco - Custom Property Example


Please share your thoughts & comments below. I try to read and respond to as many as I can. And if you would like to contribute or raise an issue with the code then visit the Gist on GitHub.