In this tutorial, you will learn how to use the Grid layout within Umbraco V7 using document types as the building blocks for the components. Out-of-the-box, Umbraco surprisingly doesn't provide any way for you to create component/blocks that can be used within the new grid layout editor. This is not ideal. Not being able to use document-types, means we cant use the Umbraco models builder. This means that if you want to use strongly-typed models in your grid layout components HTML then you will need to write a lot of code yourself. Instead of using the out-of-the-box property, I am going to show you how you can use document types with the grid layout property! If you want to level up your Umbraco skills, then read on 🤘
Introducing Doc Type Grid Editor
There is an excellent open-source community package that can be installed within your project called doc type grid editor. When installed the doc-type editor will automagically allow document types to be used with the grid layout property 😍😍😍
The doctype editor does exactly as the name implies. After installing the package you can use document types to create components that can be used by content editors within the grid editor. Using document types to define components (I also refer to them as blocks) is great. Each property defined on the document type will map to a property a content editor can use when adding that block inside of a grid. Once everything has been built, you can combine these blocks with the Umbraco model builder so you can use strongly typed objects within your views.
Getting Started With Doc Type Grid Editor
This article assumes that you understand how the grid layout property works but if you need a refresher, read this first. In this example, let us assume you have a document type created for a page and on that page, you have added a grid layout property.
For this tutorial, we will create a simple text block, which will look like this:
First, we need to install the package, this can be done via NuGet. To install the package, you can run this command in your NuGet console (you can find more information about this package here):
After the package has installed, you will need to configure it. This is done within grid.editors.config.js (found within your config folder). In this tutorial, I'm going to only enable a single editable container. I'm hoping by stripping everything out, it will make this tutorial simpler to understand. Thie container I will use will be called main, so I'll delete everything else from grid.editors.config.js. You will obviously be configuring this file based on your requirements and components. My stripped out grid.editors.config.js now looks like this:
To quickly recap on the config above. In your editor definitions, you can add a new editor definition by adding a new object (JSON) into the array list. To allow components to be added to the editor is done within the allowedDocTypes property as an array list. To allow more content editors to use more than one component editor, you add more items in the 'allowedDocTypes' section. In the example above you can see that in this editor the only doc-type allowed is RichTextBlock.
I tend to create a doctype editor on a per-feature basis. I may create a doctype editor definition for my homepage, which will only have the components I want content editors to use on that page. If the website had a sidebar, I would create a sidebar editor. For generic pages, I would use a default main container (as in the example above). With everything set up and configured, create a new page within the Umbraco backend:
Pick a layout, I've defined three layouts for my editor, full-width, half and third. I'm going to use full-width:
Click 'Add Content':
Pick the document-type editor we defined within the config above. In my example, mine was called MainContent:
As I only have one component defined in my config, the Rich Text Block, when you select 'Add Content' the rich text block should instantly load in the right-hand panel. If you have more than one allowed component you will have a list of components to select from. To recap, you use the doc-type editor to be able to define components using document types. Within grid.editors.config.js you add areas that contain components. You reference the document-type alias you want to use in each component. The properties available for content editors to use have all been defined within my document type.
That's it. Although this is a very simple tutorial, you should see the power it provides. In the next tutorial, I will go over how you can create a strongly-typed view. Happy Coding 🤘
