Introducing Positional Content

Phil Whittaker
Hi-Fi Agency
7 min readSep 5, 2018


Whilst running Hi-Fi, we kept coming across the same interesting problem again and again. It began with hotspots: placing a clickable link where the position has some important relation to the image underneath: a map, a floorplan etc. For years the logic to managing hotspots was copied and pasted between projects and subtly tweaked each time to fit the current project’s specific needs.

After some time, we worked out that a hotspot was just one form of content and that what was really needed, was the capacity to attach any defined fragment of content and store its position in relation to a background image.

Ideas Solidified

As the projects continued we often found some interesting uses for this pattern and it puzzled us as to why this wasn’t more common on websites. Why did everything have to be so single layered? It dawned on us that this was because no tooling existed. It had all been possible for years but without a specific tool, it was neither easy nor economically viable. We thought this would be a great basis for creating and releasing our own Umbraco plugin. We would create something to unify this pattern and allow other people to easily take advantage of positional content wherever they found an interesting or applicable use.

Late last year we started work on our new plugin. Its working title was initially Hotspot Editor but for obvious reasons we felt that this name limited its perceived use. We started to use it on a map of companies we created for a client and it seemed to work well.

An Inspirational Moment

Meanwhile, on a different project, we were debating a client’s predisposition to create images that contained promotional text. The argument was that composing images using Photoshop gave ultimate control, but:

- the quality of any text was reduced at higher levels of compression

- the copy wasn’t visible to SEO

- we had to go back to the designer to make any changes

- the only way to make it responsive was to create and upload separate images for each device.

We started to wonder if it would be better if we could place text over the image on the browser? And then somebody flippantly said, “wouldn’t it be great to have an editor to do this for us?”

And that was how the positional content was born.

Positional content is a property editor for Umbraco that stores the positional relationships between image and content. Alongside this we have built a high-fidelity content authoring tool for previewing and creating content positionally.

By concentrating on this one very simple idea we have made a property editor in which the developer can decide how they use the positional data stored on the front end whilst imposing as few constraints as possible on how it is used.

Image selection and cropping

The Data

The data structure of positional content is very well defined and allows great flexibility both in the level of control that the developer has in defining the data type, and the author has in creating the content. These foundations are rooted in 4 interlinking data models:

- Image — the background image

- Breakpoints — crops of the background image for each breakpoint

- Items — positional content containers

- Dimensions- positional data for each item per breakpoint

The definition of the content itself is not stored in these data models (although it does wrap them). We take advantage of Nested Content to define and store this data. Within Nested Content itself, the definition of the content is handled by document types, thus making the whole process seamless within Umbraco and easy to componentise, especially when using Model Builder.

To summarise:

Document Types > Nested Content > Positional Content

There are two types of content fragment that can be defined in Positional Content: content and settings. We’ve split these so that we can create and apply settings regardless of the content we are presenting. For example, used simply this allows the content editor to invert the colour of a content block without applying the invert property to each content definition.

These two types of content fragments (content and settings) can be defined on items, but they can also be defined for the background image. This adds an extra level of configurations- for example, in its simplest form, this could define a link around the background image.

Finally, at each breakpoint, any of these content or settings fragments can be overridden by the content author, giving complete control of what data appears for each breakpoint.

Add and position content

Using Positional Content on the Front-end

Once all your positional content data types are set up and the content editors are starting to add content, we need to output this to the website. As I’ve said before in this blog post, positional content is just a data wrapper to store the relationship of content fragments related to a background image. The choice of how to use that data is up to you. This is the real power of the plugin.

We do, however, provide some helper partials etc that will work perfectly well in any site, and will display the output correctly without any extra work. When the plugin is installed, a couple of extra files are added to the Umbraco solution:

- An HTML partial file (positionalcontent.cshtml) — accepts the positional content model from the content node and renders out all the html required to render a positional content element

- A dynamic CSS partial file (positionalcontentcss.cshtml) — creates all the breakpoint specific media queries so the content adapts to the breakpoints that have been setup.

During install we also add an extra directory to Partials. This works in the same way as Umbraco grid. It contains all the partials to render out the positional items and uses the document type alias for each partial name (the front-end positional content partial above uses the same structure so there’s no waste).

When setting up your Nested Content document types that are used as content items in the editor, it’s important to create files in the Partials/Positional Content directory, as these will used to render the preview.

Responsive Views

A Premium Editing Experience

Positional content has taken a couple of years of initial thought and around 4 months of full time development to turn it into the product it is today. We really believe that it is a unique and interesting concept with great depth that no one has fully explored yet. This is why we wanted to release it as a plugin, so that we could see what the community could create by using this tool.

However, we don’t want our work developing Positional Content to finish here. Whilst the data structures and underlying logic are very stable, our experiences and those of the content editors we are working with, tell us that the editor is what gets used the most. We are constantly finding new ways to make the editing experience as easy, rewarding and close to the finished output as possible.

We have decided that the best way for us to support the future development of Positional Content and to improve the editing experience, is to release two versions. This will comprise of a standard version that will have the full functionality as shown above and that will always be free to use. The other version will be a premium version that will concentrate on providing a premium editor experience. We will release more details on this premium version over the coming months.

We are already very excited and have some game changing features planned.

A Challenge to the Community

This blog post was just a brief introduction to Positional Content and what it does. We have found that it’s the rarest of tools: it’s very easy and fun to pick up and start using, but there are so many considerations and possibilities for configuration and adaptation that it will take a while for developers and content authors to master it fully.

We want to issue a challenge to everyone. We have made this tool so that it gets used. Its existence makes the impossible into the possible.

Explore, enjoy and let’s see where it can take us! Hopefully together we can answer the question.

What is Positional Content?

Where can I get it?

The Our Umbraco project page for Positional Content contains further details on how to download and install Positional Content. From here you can download the lite version or a getting started starter pack.