Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
A grid layout contains multiple configuration options to allow developers to tailor the grid to a very specific site design. Configuring the layout can be divided into 2 overall parts:
A layout is the general grid "container", it contains one or more sections which content editors can use to insert preconfigured rows. There are 2 main usage scenarios of layouts:
A single column layout which to the content editor will act like a full page canvas to insert elements on
A multiple column layout with a main content body, and one or more sidebar columns to insert lists or other sidebar widgets on.
You can however configure as many layouts and layout sections as you wish, each section in the layout must be given a width in columns, so editors gets an accurate preview of their layout.
A row in the grid editor contains one or more cells, which divide the row into areas where editors can enter content. So a row is merely a container of areas to insert content into. When you add a new row, you are asked to give it a name, then define cells inside the row by clicking the "+" icon. Each cell has a default width set to 4, but by clicking the inserted cell you can control its width.
It is possible to setup configurable attributes(class, rel, href) and inline styling on rows.
You can add as many cells as you like. If they overflow the total width of the row, they will be arranged after each other horizontally as you'd expect in a grid system.
Each cell can by default contain any type of editor such as textstring editors, imagespicker, embedded media or Umbraco macros. To override this behavior, uncheck the allow all editors option and you can specify which editors will be available for the row.
To understand how the grid layout editor works, we must first understand the structure of the grid layouts.
Grid layouts consists of two main areas that need to be configured, grid layout area and grid rows.
The layout area is where the overall page layout is defined. Layout areas are divided in to layout sections e.g. a sidebar section and content section. The size of the layout sections is defined in columns. For a full-width content area use max number of columns (12 for Bootstrap 3). Each layout section contains one or more rows.
Grid rows is where the actual content goes. Each row is divided into cells that contain the property editors. The size of the cells is defined in columns. Unlike the layouts sections it is possible to add more cells than the max number of columns - they will stack as they should in a grid system.
To render a property based on the grid inside a template you should use the HtmlHelper extension:
This will render the grid item with the alias "propertyAlias" from the current page models' content.
This will by default use the view /views/partials/grid/bootstrap3.cshtml you can also use other provided grid template rendering files - for example, the built-in bootstrap2.cshtml view by overloading this helper:
You can create your own custom grid rendering file for your favorite or custom grid framework implementation. Tip: copy one of the existing files as a starting point. By convention, if you create your mycustomrenderer.cshtml file in /views/partials/grid you can render the grid property like so:
Possible paths where you can add the custom Grid layout views:
The samples in this section have not been verified against the latest version of Umbraco.
A new Property Editor called the Block based Grid editor will soon be available as a substitute for the existing Grid Layout editor. For more information, see the in the Umbraco Roadmap.
Create a file in /App_Plugins/yourpackage/editor.html and add the following to the editor.html file:
Save the file and add an editor to the /App_Plugins/yourpackage/package.manifest file:
Add a new file: /App_Plugins/yourpackage/editor.cshtml - this file will handle rendering the entered data - this path is done by convention so:
view: 'editor' => views/partials/grid/editors/editor.cshtml
view: '/App_Plugins/path.html' => /App_Plugins/path.cshtml
If you wish to use something entirely different you can give the editor a separate render value which follow the same conventions.
If you are building something slightly more complex then a text area, you will need to add a controller to the grid editor view. So first add a ng-controller attribute to the grid editor html - this works like building a property editor:
To wire up a controller to this view, create the file /App_Plugins/yourpackage/editor.controller.js and add a standard angular controller declaration:
Finally, we need to tell Umbraco to load this JavaScript controller when the Umbraco application boots. This is like building a property editor. Add your JavaScript (and css dependencies) in the package.manifest file in the /yourpackage folder, and configure it to load your controller file.
So to summarize, to create a custom grid editor from scratch, you will need to:
Create a grid editor view .html file
Create a grid render .cshtml file
Create a grid editor controller .js file
Create a package.manifest to register the editor and make Umbraco load needed files
This process tries to be as close to building property editors as currently possible.
Next add this c# to the .cshtml file:
When rendering the .cshtml file will receive a dynamic model with the raw data of the editor:
So you can now use these value to build your razor output like so:
We highly recommend that you use the instead.
The Grid Layout has been marked as obsolete and development on the property editor has been discontinued. It will be removed as a core property editor with the release of Umbraco 14, planned for Summer 2024.
Returns: JSON
Gives editors a grid layout editor which allows them to insert different types of content in a predefined layout.
The basic concept of Grid Layouts.
How to setup your Grid Layout data type.
Add settings and styles.
Explanation of default Grid editors and how to customise them.
Build your own Grid editor from the ground up.
Render content created with Grid Layouts in your templates.
General guidelines when contemplating Grid Layout implementation.
Example how to add values programmatically.
The grid layout editor offers non-technical editors a more visual editing environment to layout content pages and enter content of many different kinds.
The editor offers many configuration options, and as a website implementor, you could be tempted to use the grid for nearly every kind of content entry - this is however not encouraged.
To help developers determine when to use the grid layout, we've outlined the 2 major use-cases below.
The grid should primarily be used to replace content entry in a rich text editor (RTE). Where editors before would struggle with aligning images, lists and text or using tables inside the editor to layout content in columns.
The grid solves this scenario, giving editors predefined layouts and editors to enter content. They do not have to worry about how the content is rendered, since everything is stored in a very semantic format passing on that responsibility to the developer implementing the website.
Another common scenario the grid layout editor supports are managing and inserting widgets on a page. Using the grid, editors can pick pre-made components, either text, images, embedded elements or macros and insert them in a sidebar on the page.
This could replace various setups involving content pickers, repeatable content editors and other kinds of collections of content nodes and macros.
With the above usage scenarios in mind, consider the grids limitations. First of all, all content entered into the grid is stored as a single property value on the content node, as a big JSON object. This means that as soon as the values are stored in the database, there is no managed API to drill into the grid content and target specific cell content. A grid layout is not a recommended storage of reusable content - it wasn't designed for this scenario. If you wish to reuse content in multiple pages, it is still recommended that you store these pieces of content as separate content nodes, so they can be stored, cached and queried as usual.
Keep all customisation in the /App_Plugins/ folder. This makes it easier to share across multiple projects and ensures that nothing is lost in an update process.
The grid cannot solve every problem, neither was it meant to. It absolutely shines when configured correctly and designed to solve well-defined editor tasks, like entering content in a pre-defined layout and preconfigured options. If you put a standard grid editor on every page, expecting editors to do magic, you will be disappointed - and so will your editor.
So keep the use cases basic, spend time to configure and tune the grid in detail, this will truly make your editors love you.
A grid editor is the component responsible for getting data into the grid - that could be a text field or a media picker. They're built in the same way as a property editor thus consists of 3 parts:
.html view file
.js controller
.cshtml server side renderer
The view is what the editor sees, the controller handles how it acts and the cshtml determines how the entered data is rendered in the template.
Grid editors are specified in /config/grid.editors.config.js. By default this file doesn't exist, so before you attempt to extend the configuration, make sure to create it first.
The default items in the config file are as follows below. It is recommended that you copy all of editors below before you add more, in case some of them are already in use.
If you don't add the editors below to this config file then they won't be available in your grid editors, even if there are existing grid datatypes already using these editors.
You will need to restart your site before any new customizations become available to use.
Grid editor are created in the JSON format and each editor is an object like so:
You can customize the built-in editors to tailor the grid to your need.
It is recommended that you define custom editors in a package.manifest file (not in the config file described above) like so:
While the root JSON element of /config/grid.editors.config.js is an array of grid editors, package.manifest files start with a JSON object with a number of different properties - one of them being gridEditors.
The package manifest should be placed in a folder inside the /App_Plugins/ folder - for instance /App_Plugins/{YourPackageName}/package.manifest. You can define as many grid editors you want and it can be done over multiple manifests so you can use grid editors from packages etc. With the package.manifest file in place, Umbraco will automatically pick it up during startup.
You can read more about package.manifest files in general at the Package Manifest page.
Grid editor configuration
For a grid editor, the required values are:
name: The name of the editor
alias: Unique alias of the editor
icon: Icon shown to the editor, uses same icon classes as the rest of
view the view defines the editor used to enter a value. By default Umbraco will look in /umbraco/views/propertyeditors/grid/editors for a html view to use - but you can pass in your own path
You can also add a name template for generating grid item labels using the syntax {{ value.propertyAlias }}.
If you would like to include the index position in the label, you can use {{$index}}.
If your editor links to a content, media or member node, you can use the Angular filter {{ value.udi | ncNodeName }} to show the node name rather than the node ID.
If your editor is a rich text editor, you can use the Angular filter {{ value | ncRichText }} to show the unformatted text.
The built-in views you can use are:
textstring
rte
embed
macro
media
In most cases you will either use the textstring or media view, or built your own from scratch. The textstring and media editors come with some additional configuration to make it quick to customise these.
Sample textstring config
In this sample, the config.style value is applied to the editor so users can see an accurate preview in the backoffice. This will be applied as as inline styling to the textarea in the backoffice.
The config.markup is the string rendered server side in your template. #value#will be replaced with the actual value
Sample media config
In this sample config.size will resize the image according to height and width. The above example will result in a rendered image that is 200x200 pixels no matter the size of the uploaded image. If the ratio of the size differs from the uploaded image it is possible to set a focal point that determines how the image should be cropped.
Sample macro config
In this sample a new option will appear in the Choose type of content with direct access to the macro.
For this example, the default grid configuration has been used.
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
A grid layout can also expose custom settings - such as data-attributes or styling options - on each cell or row. This allows editors to use a friendly UI to add configuration values to grid elements. When custom settings and styles are applied, they will by default be included in the grid html as either html attributes or inline styles.
These settings and styles must be configured by developers when setting up the grid layout data type.
To add a setting, click the edit settings link. This will expand a dialog showing you the raw configuration data. This data is in the JSON format and will only save if it's valid JSON.
The settings data could look like this, with an object for each setting:
The different values are:
label : Field name displayed in the content editor UI
description : Descriptive text displayed in the content editor UI to guide the user
key : The key the entered setting value will be stored under.
view : The editor used to enter a setting value with.
prevalues : For views that need predefined values, e.g. the radiobuttonlist view.
modifier (optional) : A string formatter to modify the output of the editor to prepend or append extra values.
applyTo (optional) : States whether the setting can be used on a cell or a row. If either not present or empty, the setting will be shown both on Rows and Cells.
label and description are straight-forward.
key defines the alias the configuration is stored under and by default the alias of the attribute will also be the attribute on the rendered html element. In the example above any value entered in this settings editor will be rendered in the grid html as:
By changing the key of the setting you can modify the <div> element's attributes like class, title, id or custom data-* attributes.
view the view defines the editor used to enter a value. By default Umbraco comes with a collection of prevalue editors:
textstring
textarea
radiobuttonlist
mediapicker
imagepicker
boolean
treepicker
treesource
number
multivalues
Alternatively you can also pass in a path to a custom view like "/App_Plugins/grid/editors/view.html"
prevalues is for views that need predefined values, e.g. the radiobuttonlist view. Prevalues are defined as strings in an array:
and will translate in to three different options where each string will become a radiobutton. The strings represent the value of the options.
Prevalues can also be defined as an object of label/value allowing to have a displayed label instead of showing the actual underlying value. You can even mix and match these and use both label/value prevalues and string prevalues in the same configuration:
modifier is a basic way to prepend, append or wrap the value from the editor in a string. This is especially useful when working with custom styles which often requires additional values to function. For instance if you want to set a background image you can get an image path from the image picker view. But in order for it to work with css it has to be wrapped in url(). In that case you set the modifier to url({0}) which means that {0} is replaced with the editor value.
applyTo defines what this setting can be applied to. It should be either row or cell as a string.
A JSON object can also be used if you need a more specific configuration. A JSON configuration could look like this:
This would ensure the setting can only be used on rows named Article or Headline, or on cells sized: 4, 8 or 6. If it should only apply to cells you can remove the row property. If it should apply to all rows you can specify it by having the row property with null or an empty string as value.
There are many ways to combine these, here are some samples:
You can add multiple settings and styles configurations on a data type. This is done by creating a new setting or style object. Remember to separate the objects with a comma.
It is possible to use settings and styles to add full-width background-images, background-colors and so forth. Make sure the surrounding section is full-width (12 columns by default) and the rows inside it will automatically become full-width.
