Ten Grids Later

I've just realized that I've spent more than one hour in front of my computer screen with my hands hovering above the keyboard, thinking about what I would like to say in this post. There are a lots of things I could talk about as I’ve spent almost six years working every day and every working hour (there are quite a few) with the same thing that brought all of us here: Umbraco.

Doing a quick calculation, around of 35% of my life is dedicated to working with our favorite content management system and that is translated into lots of creative, frustrated, fun and rewarded times... Yes, developers have emotions as well :)

But I had to choose one topic for today, so I'll talk about the Grid.

The most important thing to do when we start a new project based on the Grid is to “think like a Grid”

Back before Codegarden 2014, the rest of the team and I spent a lot of time developing and polishing the Grid editor and all the uSky stuff we presented at the event. Over the last year, we have learned how to use it, though finding the best way has been a winding road full of obstacles.

I would like to take advantage of this post to share our experiences, best practices, how to “think like a Grid”, and the different essential aspects to consider for projects based on it.

What we learned

The most important thing to do when we start a new project based on the Grid is to “think like a Grid”. The notion of how to organize content is different, the number of needed Document Types and properties will be drastically reduced. We must change our way of analyzing and interpreting the information.

Lots of content can now be edited and stored within the Grid itself, so it is important to identify two types of content: Grid-friendly content and Grid-unfriendly content.

Content is Grid-friendly when it is specific to the page it appears on, like the blurb on an About Us page. On the other hand, content is Grid-unfriendly if it will be reused elsewhere on the site, like products, news and else.

The golden rule could maybe be: reusable content can’t and shouldn’t be stored within a Grid, but all other content can (or might)!

Why is it so important? First, because by design the grid isn’t a container for reusable content and is not prepared for that. Even more relevantly, the end user is the editor and we would like to make them happy and make their life better. So, it’s more understandable for them if each piece of content is edited in its right, single, and natural place.

In some cases, some content which has to appear within the grid seems to be impossible to edit because of its data/HTML complexity. But new tools from the community have been created to make it possible, and far easier, which we will talk about in the next section.

Before that, let’s have a look at ten rules which, in my opinion, are the most important to follow on implementing a Grid project:

  1. Default settings which come with the Grid are only for reference.
    Use them only if your project really needs them. A radical position would be to delete all of them before starting once you’ve become familiar with Grid projects.

  2. Default view “Bootstrap 2” and “Bootstrap 3” are for reference as well.
    Do not hesitate to change them, create your own and use others from the community. Obviously not all projects use the bootstrap framework so, above all,  do not base your decision to use this framework only because of those default files.

  3. Create several Grid configurations by project.
    The home page won’t have the same layout as the inner page: not all pages have the same layout. Putting them together could be very hard to manage for the end user.

  4. Create only the Grid/Row layouts that are really needed, and only allow the editors required for them within these areas.
    Don’t overload the grid with options which are not necessary. It will make the grid harder to use and might be confusing.

  5. Make sure that every editor combination makes sense and it can't break the original markup.
    A wide banner slider for instance should be placed within a large row, not within a three columns row.

  6. Use the settings/styles for any kind of style configuration.
    Preferably use "Setting" rather than styles. By default styles inject in-line styling which isn’t very nice. And specify where they can be used, e.g. "applyTo": "row|cell"

  7. Disable Image/Macro/Video/Embedded from the default RTE configuration.
    The Grid solves those scenarios, giving end users predefined layouts and simple editors to enter content. Only keep the simplest option: Bold/Links/Styles...

  8. Never use RTE for complex blocks of HTML.
    Third party packages exist for that.

  9. Never store reusable content in the Grid.
    As mentioned before, the Grid wasn't designed for this and doesn’t really make sense.

  10. Make the Grid beautiful.
    Add a dedicated CSS file to give the Grid a good look. The end user will appreciate that.

What we did

As I mentioned before, in a lot of cases we will need to edit complex HTML structure within our Grid. Components such as sliders, carousels, tabs, highlighted content and others are very common within modern web designs. We can create DocumentType/DataType structures to solve that, but it’s too much engineering for too little content and adds complexity to the project which isn't good for the end user's understanding.

So, there are different ways to solve that:

1) Create your own grid editor

This is the natural and native way to resolve that. But it takes time, which we usually don’t have too much of and we also need basic AngularJS knowledge.

See more information:

Hopefully, we will see in the future a lot of new Grid editors shared and ready to use from the Umbraco community, but it isn't the case yet.

To help with Grid editor creation and management, a few months ago we created the LeBlender editors manager package. It allows Grid editor management through a simple UI without any line of code. We made this package in the hope to boost and improve the community's sharing of their custom Grid editors.

See more information:

Think like an end user, at least think about how they will use the Grid. Everything has to be clear, handy, and easy.

2) Using macros

This was the first approach we took when we started implementing Grid projects. It is great, easy and fast to implement. Macros are a component that we already know and are easy to use.

You can read this post to learn how to use macros with the Grid editor.

But this approach has some disadvantages:

  • More complexity for the end user. Adding a macro within the Grid is a different process from adding an editor, which can be confusing for the end user.
  • We can’t configure which macros are allowed within which Grid areas.
  • We add more dependency to the database, creating more deployment and versioning complexity.

3) LeBlender editor or Doc Type Grid Editor

This is definitely the easiest and best way to create complex HTML structure within the Grid.

Both packages have very similar behaviors, with two different approaches:

Leblender editor is part of the Leblender project I mentioned before. It’s a Grid editor that allows you to create a set of properties based on DataTypes to make complex HTML structures or lists of them.

Doc Type Grid Editor does the same thing but using a Document Type approach, and can be used with Nested Content to create lists of elements:

Both packages are valid and very useful. So you can use whichever seems more appropriate to you and fits better with your project specification.

Note: Doc Type Grid Editor can be used with LeBlender editor manager, but that’s for another post :)

What We Bring

Today we’re bringing something both new and fresh, a simple and small Umbraco package that I’m sure you will love.

It’s called LePainter, and allows us to see a graphical preview of the Grid’s settings/styling configuration within the Umbraco backend itself.

For example, if the end user sets a background image for the row, they will have a live preview of it within the backend Grid:

Or the user can add a class name to the row to set the background color and see it update:


This way, the end user has direct information on the setting/styling configurations without opening the settings/stylings panel or checking the front end.

LePainter works the same way as the setting/styling configurations in the front end:

  • Setting configurations add attribute values within the current row/cell tags.

  • Styling configurations add style attributes within the current row/cell tags.

How to install

You can download it here:

At the end of the day, what we all hope to hear from the end users is "Thanks guys, it’s awesome, Umbraco is the best CMS ever, #h5yr."

or by nuget:

LePainter is a property editor, so you just need to create a new DataType of type LePainter and add it to the Document Types which use the Grid. This property doesn't store any data and doesn't interact with the editor, you can just add it within the generic property tab to avoid confusion.

LePainter has only one prevalue Stylesheet Path that allows injecting a new CSS file into Umbraco which can be used for backend Grid styling.

Important: LePainter interacts directly on the native backend grid markup, so be especially careful to not break the initial html structure.

To Conclude

After having worked on more than ten Grid projects, I can definitely say that we have learned lot of things.

Maybe the most relevant conclusion I can highlight here is that this job is not easy and it’s a mistake to believe that. Umbraco Grid was designed to make end users’ lives better, not developers’. Grid projects have to be treated with love, detail and finesse from beginning to the end.

At the end of the day, what we all hope to hear from the end users is "Thanks guys, it’s awesome, Umbraco is the best CMS ever, #h5yr."

Antoine Giraud

Antoine is French but has been living in Spain for the last 15 years. He is a co-founder of Spanish-based LECOATI, the first south European Umbraco Gold Partner. He had an important role in the creation of the Umbraco Grid, and is the author of Umbraco packages such as uMirror, uMobile, and LeBlender. A father of two kids, when he is not coding he spends his time with his family looking for some new rocks to climb or some of best surf spots on the Spanish west coast.

comments powered by Disqus