Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Learn more about the default property editors that ships with an Umbraco installation.
A Property Editor is the editor that a Data Type references. A Data Type is defined by a user in the Umbraco backoffice and references a Property Editor. In Umbraco a Property Editor is defined in a JSON manifest file and associated JavaScript files.
When creating a Data Type, specify the property editor for the Data Type to use by selecting from the "Property editor" list (as shown below).
Umbraco comes pre-installed with many useful property editors.
Learn more about the Umbraco backoffice which is the admin side of your Umbraco website.
In this article you can learn more about the common terms and concepts that are used throughout the Umbraco backoffice.
When you go to the backoffice for the first time, you're presented with the login screen.
A section in Umbraco is where you do specific tasks related to that section. For example Content, Settings and Users. You can navigate between the different sections of the backoffice by clicking the corresponding icon in the section menu.
The Section menu is the horizontal menu located on the top of the backoffice.
A tree is a hierarchical list of items related (and usually restricted) to a specific concept, like for example content or media.
A node is an item in a tree. Media section items appear as nodes in the Media tree, while pages and content are displayed in the Content tree, and so on.
A dashboard is the main view you are presented with when entering a section within the backoffice. It can be used to show valuable information to the users of the system.
Default dashboard in the content section
An editor is what you use to edit different items within the backoffice. There are editors specific to editing stylesheets, there are editors for editing Macros, and so forth.
Content is what you find in the Content section. Each item in the tree is called a content node. Each content node in the content tree consists of different fields, and each of them is defined by a Document Type.
Document Types define the types of content nodes that backoffice users can create in the content tree. Each Document Type contains different properties. Each property has a specific Data Type for example text or number.
Every Document Type has properties. These are the fields that the content editor is allowed to edit for the content node.
Each Document Type property has a Data Type that defines the type of input of that property. Data Types reference a Property Editor and are configured in the Umbraco backoffice in the Settings section. A Data Type can be something basic (text string, number, true/false) or more complex (multi-node tree picker, image cropper, etc).
A property editor is a view used by Data Types to insert content into Umbraco. An example of a property editor is the Textarea. It's possible to have many Textarea Data Types with different settings that all use the Textarea property editor.
Media items are used to store assets like images and video within the Media section and can be referenced from your content.
Media Types are similar to Document Types in Umbraco, except they are specifically for media items in the Media section.
Umbraco comes with 3 default Media Types: File, Folder, and Image.
A member is someone who has access to signup, register, and login into your public website and is not to be confused with Users.
Similar to a Document Type and a Media Type. You are able to define custom properties to store on a member such as Twitter username or website URL.
A Template is where you define the HTML markup of your website and also where you output the data from your content nodes.
A macro is a reusable piece of functionality that you can reuse throughout your site. Macros can be configured with parameters and used on content nodes that have a Rich Text Editor, a Grid editor, or a Macro Picker property. You can define what macros are available for your editors to use. When an editor inserts a macro it will prompt them to fill out any of the defined parameters for the macro.
A parameter editor defines the usage of a property editor for use as a parameter for Macros.
A user is someone who has access to the Umbraco backoffice and is not to be confused with Members. When Umbraco has been installed a user will automatically be generated with the login (email) and password entered during installation. Users can be created, edited, and managed in the User section.
Content Templates provide a blueprint for content nodes based on an existing node.
Alias: Umbraco.Decimal
Returns: decimal
In the example above the possible values for the input field would be [8, 8.5, 9, 9.5, 10]
All other values will be removed in the content editor when saving or publishing.
If the value of Step Size is not set then all decimal values between 8 and 10 is possible to input in the content editor.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
In this article you can learn how to use the build in email property editor
Alias: Umbraco.EmailAddress
Returns: String
Displays an email address.
The Email Address Property Editor does not come with any further configuration. The property can be configured once it has been added to a Document Type.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
The value sent to an EmailAddress property needs to be a correct email address, For example: name@domain.com.
It is recommended that you set up validation on this property, in order to verify whether the value added is in the correct format.
Alias: Umbraco.CheckBoxList
Returns: IEnumerable<string>
Displays a list of preset values as a list of checkbox controls. The text saved is an IEnumerable collection of the text values.
Unlike other property editors, the Prevalue IDs are not directly accessible in Razor.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
.
.
You can expand trees by clicking the down arrow to the left of the node or by double-clicking the node.
A package is the Umbraco term for an add-on or plugin used to extend the core functionalities in Umbraco. The packages can be found on the , and the can also be browsed directly in the backoffice of the Umbraco CMS.
The only setting that is available for manipulating the Date property is to set a format. By default the format of the date in the Umbraco backoffice will be YYYY-MM-DD
, but you can change this to something else. See for the supported formats.
See for more information about why the dynamic approach is obsolete.
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 .
See the example below to learn how a value can be added or changed programmatically to an Email-address property. To update a value of a property editor you need the .
You can use dictionary items to translate the values of a Checkbox List property editor in a multilingual setup. For more details, see the article.
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 .
Alias: Umbraco.DateTime
Returns: DateTime
Displays a calendar UI for selecting dates which are saved as a DateTime value.
There are two settings available for manipulating the DateTime property.
One is to set a format. By default the format of the date in the Umbraco backoffice will be YYYY-MM-DD HH:mm:ss
, but you can change this to something else. See MomentJS.com for the supported formats.
The second setting is "Offset time". When enabling this setting the displayed time will be offset with the servers timezone. This can be useful in cases where an editor is in a different timezone than the hosted server.
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.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Returns: MediaWithCrops
Returns a path to an image, along with information about focal point and available crops.
When the Image Cropper is used on a Media Type the crops are shared between all usages of a Media Item. This is called global crops.
If the Image Cropper is used on a Document Type, the file and crops will be local to the Document.
Notice that it is possible make local crops on shared Media Items via the Media Picker Property Editor.
You can add, edit & delete crop presets the cropper UI can use.
The Image Cropper provides a UI to upload an image, set a focal point on the image, and use predefined crops.
By default, images in the Image Cropper will be shown based on a set focal point and only use specific crops if they are available.
The Image Cropper comes with 3 modes:
Uploading an image
Setting a focal point
Cropping the image to predefined crops
The editor exposes a drop area for files. Select it to upload an image.
By default, the Image Cropper allows the editor to set a focal point on the uploaded image.
All the preset crops are shown to give the editor a preview of what the image will look like on the frontend.
The editor can fit the crop to the image to ensure that the image is presented as intended.
ImageSharp.Web is image processing middleware for ASP.NET.
We bundle this package with Umbraco and you can therefore take full advantage of all its features for resizing and format changing. Learn more about the built in processing commands in the official ImageSharp documentation.
The Image Cropper comes with an API to generate crop URLs. You can also access the raw data directly as a dynamic object.
For rendering a cropped media item, the .GetCropUrl
is used:
The third parameter is HtmlEncode
and is by default set to true. This means you only need to define the parameter if you want to disable HTML encoding.
Or, alternatively using the MediaWithCrops
extension method:
Set the htmlEncode
to false so that the URL is not HTML encoded
To update a content property value you need the Content Service.
The following sample demonstrates how to add or change the value of an Image Cropper property programmatically. The sample creates an API controller with an action, which must be invoked via a POST request to the URL written above the action.
If you use Models Builder to generate source code (modes SourceCodeAuto
or SourceCodeManual
), you can use nameof([generated property name])
to access the desired property without using a magic string:
Crop URLs are not limited to usage within a view. IPublishedContent
has a GetCropUrl
extension method, which can be used to access crop URLs anywhere.
The following sample demonstrates how to use GetCropUrl
to retrieve URLs for all crops defined on a specific image:
Below the example to output a PNG using ImageSharp.Web format command.
Alias: Umbraco.ContentPicker
Returns: IPublishedContent
The content picker opens a panel to pick a specific page from the content structure. The value saved is the selected nodes UDI
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.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.Listview
Returns: IEnumerable<IPublishedContent>
List View display a list of categories when it is enabled on a Document Type that has children.
If enabled, editors will be able to see multiple children from a list on a content node that has children. When not enabled, no list will be shown and all children will be shown in the Content Tree.
Defines how many child content nodes you want to see per page. This will limit how many content items you will see in your list. If you set it to 5, then only 5 content items will be shown in the list.
Will sort your list by the selection you choose in the dropdown. By default it selects "Last edited" and you get the following three columns:
Last edited - When the content node was last edited and saved.
Name - Name of the content node(s).
Created by - This is the user who the content node was created by.
You can add more sorting to this list by adding more datatypes to the columns in the "Columns Displayed" section.
You can select order of the content nodes displayed, "Acsending" or "Descending". The order is affected by the "Order By" selection.
It is possible to add more columns to the list, via adding the properties through the dropdown. These properties are based on the Data Types which are used by the Document Type. It will show up in the dropdown by its alias and not the name on the property.
Once you have selected a column that you want to display, the next thing you want to do is define what its name should be and what kind of value it should display. You can also move the headers around, re-ordering how the headers should look. This is done by the move icon on the left side of the alias.
The template section is where you define what kind of value you want to display. The value of the column is in the value
variable.
The list view comes with two layouts by default. A list and a grid view. These views can be disabled if you are not interested in any of them.
A minimum of one layout needs to be enabled for the list view to work.
You can also make your own layout and add it to the settings. For example, if you wanted to change the width or length of the grid, you will be able to do so.
Select what kind of action is available on the list view.
Allow bulk publish - content only
Allow bulk unpublish - content only
Allow bulk copy - content only
Allow bulk move
Allow bulk delete
Changes the icon in the backoffice of the listview. By default it will look like the image below.
You can change the name of the listview itself. Default if empty: 'Child Items'.
Enable this to show the content app by default instead of the list view
The {{ value }}
will take the value of the Email property and display it in the list, as shown on the image below.
First, a Member Picker property needs to be present on the content item. In this example, the child item
has gotten a Member Picker Data Type with the alias of isAuthor
.
Now that the child item has a member and the value that should be displayed is the name of the picked value, the next step is to reconfigure the template value in the listview setting.
Alias: Umbraco.UploadField
Returns: string
Adds an upload field, which allows documents or images to be uploaded to Umbraco.
You can define which file types should be accepted through the upload field.
For uploading and adding files and images to your Umbraco project, we recommend using the Media Picker.
Find the full documentation for the property in the Media Picker article.
In code, the property is a string, which references the location of the file.
Example: "/media/o01axaqu/guidelines-on-remote-working.pdf"
The samples in this section have not been verified against the latest version of Umbraco.
Instead, we recommend using the Media Picker for uploading files to your Umbraco website.
See the example below to see how a value can be added or changed programmatically. To update a value of this property editor you need the Content Service and the Media Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.MarkdownEditor
Returns: System.Web.HtmlString
This built-in editor allow the user to use the markdown formatting options, from within a tinyMCE-like interface.
There are three settings available for manipulating the Markdown editor property.
Preview toggles if a preview of the markdown should be displayed beneath the editor in the content view.
Default value is inserted if no content has been saved to the Document Type using this property editor.
Overlay Size is used to select the width of the link picker overlay in the content view.
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.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.ColorPicker
Returns: String (Hexadecimal)
Returns: Umbraco.Cms.Core.PropertyEditors.ValueConverters.ColorPickerValueConverter.PickedColor (When using labels)
The Color picker allows you to set some predetermined colors that the editor can choose between.
It's possible to add a label to use with the color.
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.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
In this article you can learn more about the various sections you can find within the Umbraco Backoffice.
A section in Umbraco is where you perform specific tasks related to a particular area of Umbraco. For example Content, Settings and Users are all sections. You can navigate between the different sections by clicking the corresponding icon in the section menu which is positioned at the top of the Backoffice.
The Section menu is the horizontal menu located at the top of the Umbraco Backoffice.
There are eight default sections that come with Umbraco:
The Content section contains the content of the website. Content is displayed as nodes in the content tree. Nodes can also show content state:
Grayed out nodes have not been published
In order to create content, you must define it using Document Types.
The Media section contains the media for the website. By default, you can create folders and upload media files (images and PDFs). You can customize the existing media types or define your own from the Settings section.
The Settings section is where you can work with the website layout files, languages, and define media and content types. In this section, you can also find the Log Viewer to browse through your log files.
The Settings tree consists of:
Document Types
Media Types
Member Types
Data Types
Macros
Relation Types
Log Viewer
Languages
Content Templates
Templates (.cshtml
files)
Partial views (.cshtml
files)
Partial View Macro Files (.cshtml
files)
Stylesheets (.css
files)
Scripts (.js
files)
The Settings section of the Umbraco backoffice has its own set of default dashboards. For more information, see the Settings Dashboards article.
In this section, you can browse and install packages into your Umbraco solution. You can also get an overview of all the installed packages as well as uninstall packages you no longer need.
Manage, create, and customize Backoffice users and user groups.
Manage, create, and customize members and member groups.
You can install Umbraco Forms directly from the Backoffice by clicking the install button. Once installed, this section is where you create and manage your forms.
This is the section where you create and manage your dictionary items.
In the top-right corner, you'll find a search tool, which is also accessible by hitting CTRL + Space
on your keyboard.
Next to the search tool, there is a help section. In the help section you can find Backoffice tours and links to Umbraco resources such as documentation and UmbracoTV.
There is also a small 'user section' with shortcuts to edit the currently logged in user, and view their most recent activities.
Along with the default sections that come with Umbraco, you can create your own Custom Sections.
A User can access a particular section based on the User Group permissions.
Learn more about how to configure the permissions in the article about backoffice users.
Alias: Umbraco.ColorPicker.EyeDropper
Returns: string
The Eye Dropper Color picker allows you to choose a color from the full color spectrum using HEX and RGBA.
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.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.Label
Returns: String
Label is a non-editable control and can only be used to display a pre-set value.
If you want to set a value other than a String, you can define the data using one of the other available Data Types. These include Decimal, Date/time, Time, Integer, and Big integer.
There is also a Value Type: Long string if you need to set a long string value for your Label.
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.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.MemberPicker
Returns: IPublishedContent
The member picker opens a panel to pick a specific member from the member section. The value saved is of type IPublishedContent.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.MediaPicker3
Returns: IEnumerable<MediaWithCrops>
or MediaWithCrops
This property editors returns a single MediaWithCrops
item if the "Pick multiple items" Data Type setting is disabled or a collection if it is enabled.
Use setting to limit the picker to only select Media Items of these types.
Use this setting to enable the property to contain multiple items. When this is enabled the property editor returns an IEnumerable<MediaWithCrops>
.
You can still set the maximum amount to 1. Do so when you want to retrieve a collection but only allow the Content Editors to select one Media Item.
Use this setting to enforce a minimum and/or maximum amount of selected Media Items.
It is not possible to set a maximum amount when the "Pick multiple items" feature is disabled.
This setting is used to limit the Media Picker to certain parts of the Media Tree.
Use this setting to overrule user permissions, to enable any user of this property to pick any Media Item of the chosen Start node.
When this setting is enabled, a user who doesn't normally have access to the media selected as "Start Node" (/Design in this case), can access the media when using this particular Media Picker. If no Start node has been defined for this property any content can be viewed and selected of this property.
Enable the focal point setter, do only enable this if the focal point is used or if you have Image crops defined.
Define local image crops. Local image crop data is stored on the document in this property. This means it can differentiate between documents.
This is different from Global crops as they are defined on the Media Item, making the crops shared between all usage of that Media Item.
Global crops are configured on the Image Cropper property of the Image Media Type
Both local and global crops are retrieved using the method GetCropUrl
. If crops with identical aliases are defined both locally and globally, the locally defined crops are always prioritized by GetCropUrl
.
The following is an example of how to retrieve a crop from a MediaWithCrops
entry:
You can retrieve globally defined crops explicitly by using GetCropUrl
on the UrlHelper
:
The following sample will update a single image in a Media Picker.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
We highly recommend that you use the instead.
This updated property contains more customizable features, and we recommend using this over the Media Picker, which is also marked as the old version of the picker.
Alias: Umbraco.MediaPicker
Returns: IEnumerable<IPublishedContent>
or IPublishedContent
This property editors returns a single item if the "Pick multiple items" Data Type setting is disabled or a collection if it is enabled.
Use Settings to overrule user permissions, to enable any user of this property to pick any Media Item of the choosen Start node.
When this setting is enabled, a user who doesn't normally have access to the media selected as "Start Node" (/Design in this case), can access the media when using this particular Media Picker. If no Start node has been defined for this property any content can be viewed and selected of this property.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.MemberGroupPicker
Returns: string
The Member Group Picker opens a panel to pick one or more member groups from the Member section. The value saved is of type string (comma separated IDs).
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
You can also add multiple groups by creating a comma separated string with the desired member group IDs.
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:
Alias: Umbraco.Integer
Returns: Integer
Numeric is an HTML input control for entering numbers. Since it's a standard HTML element the options and behaviour are all controlled by the browser and therefore is beyond the control of Umbraco.
This allows you to set up a minimum value. If you will always need a minimum value of 10 this is where you set it up and whenever you use the datatype the value will always start at 10. It's not possible to change the value to anything lower than 10. Only higher values will be accepted.
This allows you to control by how much value should be allowed to increase/decrease when clicking the up/down arrows. If you try to enter a value that does not match with the step setting then it will not be accepted.
This allows you to set up a maximum value. If you will always need a maximum value of 100 this is where you set it up. It's not possible to change the value to anything higher than 100. Only lower values will be accepted.
By casting the output as an int it's possible for you to do mathematical operations with the value.
You can also render the output by casting it to a string, which means you will not be able to do mathematical operations
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.MultipleTextstring
Returns: array of strings
The Repeatable textstrings property editor enables a content editor to make a list of text items. For best use with an unordered-list.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
To add multiple values to the repeatable text strings property editor you have to put each value on a new line. This can be achieved using either \r\n\
or Environment.NewLine
.
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:
Alias: Umbraco.RadioButtonList
Returns: string
Pretty much like the name indicates this Data type enables editors to choose from list of radio buttons and returns the value of the selected item as string.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.Slider
Returns: decimal
or Umbraco.Core.Models.Range<decimal>
Pretty much like the name indicates this Data type enables editors to choose a value with a range using a slider.
There are two flavors of the slider. One with a single value picker. One with a minimum and maximum value.
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:
Alias: Umbraco.MultiNodeTreePicker
Returns: IEnumerable<IPublishedContent>
The Multinode Treepicker allows you to configure the type of tree to render and what part of the tree that should be rendered. For content it allows you to select a dynamic root node based on the current document using the multinode tree picker.
Set the type of node, the root node of the tree, or query for the root node.
For querying content you can specify a dynamic root:
When you specify the dynamic root, you are able to navigate the tree relative to a node.
You have the following options:
Root
The root is the first level item of the current nodes subtree.
Parent
The parent is the nearest ancestor of the current node.
Current
The current node. Be aware a picker that uses the current node, cannot pick anything when the current node is created, because it do not have any children.
Site
The nearest ancestor of the current node that has a domain assigned.
Specific node
A specific node that you have to choose in the tree
Often an origin is a good dynamic root. It is also possible to execute multiple steps from the origin to navigate the tree to find another root.
You have the following options:
Nearest Ancestor or Self
Finds the nearest ancestor or the item itself, that fits with one of the configured document types.
Furthest Ancestor or Self
Finds the furthest ancestor or the item itself, that fits with one of the configured document types.
Nearest Descendant or Self
Finds the nearest descendant or the item itself, that fits with one of the configured document types.
Furthest Descendant or Self
Finds the furthest descendant or the item itself, that fits with one of the configured document types.
Custom
Execute a custom query step by specifying the name. This requires custom code to add the new query step.
Each query step takes the output from the last step (or the origin) as input.
Custom query steps can be used to solve some specific use cases.
To add a custom query step you need to append it to the existing query steps. This can be done from a composer:
The implementation of a query step takes in a collection of origins and information about the query step. The collection is taken from where the name specified in the UI can be found.
The code required to create a custom query step is like in the below example.
You can inject dependencies into the constructor. Some interesting dependencies could be custom repositories, or the IVariationContextAccessor
, if you wanna use the current culture.
The ExecuteAsync
method gets a collection of content keys from the last executed query step or the origin. It has to return a new collection of content keys.
Allow or disallow tree nodes with a certain content type alias.
Enter typeAlias,altTypeAlias
to only allow selecting nodes with those alias'. Enter !typeAlias,altTypeAlias
to only allow selecting nodes not with those alias'.
Set a limit on the number of items allowed to be selected.
Consider the following tree structure where Document Type alias is presented in square brackets.
Codegarden
2023 [year]
Talks [talks]
...
Umbraco anno MMXXIII [talk]
Stages [stages]
Social Space [stage]
No 10 [stage]
No 16 [stage]
The Theatre [stage]
2022 [year]
Talks [talks]
...
Stages [stages]
Main Stage [stage]
The Barn [stage]
The Theatre [stage]
Consider configuring a picker on the talk Document Type to choose a stage of the talk. Here you only want to present the stages for the actual year. To do this, you need to choose the parent as origin.
Imagine being on the Umbraco anno MMXXIII
node. This means the collection of content keys passed into the first query step will only contain the Talks
content node.
First you can then query for the nearest ancestors of type year
. This means the 2023
will be returned.
Next, you can query for the nearest descendants of type stages
.
When opening the picker on the Umbraco anno MMXXIII
node, it will now show the children of the node on path Codegarden => 2023 => Stages
.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.MultiUrlPicker
Returns: IEnumerable<Link> or Link
Multi Url Picker allows an editor to pick and sort multiple urls. This property editor returns a single item if the "Maximum number of items" Data Type setting is set to 1 or a collection if it is 0. These can either be internal, external or media.
If Max number of items
is configured to 1
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
This example uses a generic field on a child item and displays it in the list.
This will take the value picked up by the member picker.
And display it in the listview. Shown in the example below:
Function | Shortcut | Further explanation |
---|---|---|
Function | Shortcut |
---|---|
Nodes have unpublished versions (but are currently published)
Nodes are protected from the public (can only be accessed by a logged in Member)
Nodes are currently locked/non-deletable
Nodes are containers (a List View for example)
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 .
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 .
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 .
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 .
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 .
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 .
You can use dictionary items to translate the values of a Radiobutton List property editor in a multilingual setup. For more details, see the article.
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 .
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 .
First you have to specify a origin, from where the query will start.
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 .
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 .
toggle bold text
Ctrl + B
toggle italic text
Ctrl + I
insert link
Ctrl + L
This opens the Select Link interface.
toggle quote
Ctrl + Q
toggle code block
Ctrl + K
insert image
Ctrl + G
This opens the Select Media interface.
toggle ordered list
Ctrl + O
toggle unordered list
Ctrl + U
toggle heading
Ctrl + H
This toggles between h1, h2 and off.
toggle a hr
undo
Ctrl + Z
redo
Ctrl + Y
select all
Ctrl + A
copy
Ctrl + C
paste
Ctrl + V
The Block Editors are property editors that enabled you to build advanced editor tools using a set of predefined Document Types.
Umbraco CMS currently ships with two Block Editors: the Block List and the Block Grid.
Learn how to create custom views for the blocks used in your Block Grid or Block List property editors.
Get an overview of available configurations for the label properties.
You can choose to customize your editing experience by implementing a custom view for each Block Type of a Block Editor.
By picking a custom view you overwrite the backoffice UI for the given block with your own. This enables you to define how a block should be presented. It can, however, also include interactive elements and be a full custom solution to how data is manipulated. In the Block List Editor the Inline Editing Mode must be disabled for custom backoffice views to appear.
Currently you can only pick HTML files for a custom view. These views are powered by AngularJS and you can write any AngularJS logic.
Your HTML can be anything. If you use it as a representation of the content you would also want the full view to be clickable. This would then open the default editor for editing of your content.
The following example displays the property with the alias headline
together with the description
inside a button to edit your block.
If you would like to display properties of settings
, you can access these by using block.settingsData.myPropertyAlias
.
A custom view of Block List Editor needs to have the 'blockelement__draggable-element' class presented to define which part of the Block is draggable.
Example:
This is not relevant for the Block Grid Editor where all Blocks are draggable by default..
Blocks of the Block Grid Editor can have Areas. These Blocks require their Custom View to define where the Areas should be inserted.
This enables you to wrap and place the Areas as you need.
The Areas is inserted through Web Component Slots. A slot is a native HTML tag.
These Area slots can be generated automatically via this AngularJS Directive:
Example of a Custom View wrapping the Areas within a green border:
You can also define where each Area should be inserted. This is relevant if you like the Areas to appear differently than the provided grid setup of Areas.
As a reference here is an example of the HTML output of the umb-block-grid-render-area-slots
AngularJS Directive:
To achieve this you need to add a custom AngularJS controller to your custom view, using the ng-controller
attribute:
Create a folder inside the App_Plugins
folder called 'CustomBlockView'.
Create two files within the CustomBlockView file: package.manifest
and customBlock.controller.js
.
Add the following JSON to the package.manifest
file:
Umbraco will parse all package.manifest
files and load any resources they reference into the backoffice during startup.
The second file, customBlock.controller.js
, will be used to register the 'customBlockController' defined using the ng-controller
attribute in your custom view.
To register the controller, add the following lines of code:
Your block may enable you to 'pick' an image to use as the background for a particular block. If you try to display this image directly in the view using block.data.image
, you will see the unique ID and not the image.
There are two approaches to displaying the actual image in your custom block view. Either use a filter in your custom view or retrieve the image through the AngularJS controller.
By using the AngularJS filter called mediaItemResolver
, it is possible to retrieve the image directly from your custom view file. You will need to create a variable that then uses the mediaItemResolver
filter on the Media Picker property. This variable is then used to retrieve the image URL in an <img>
HTML tag.
In the following example, a mediaItem
variable is defined and used to set the ng-src
value on the image tag. This will retrieve the image into your custom view.
It is also possible to get the ImageUrl
by using the unique ID in an AngularJS controller.
Amend the customBlock.controller.js
file, by injecting the mediaResource
to retrieve the image from the ID:
The Custom View should then be updated to use the imageUrl
property to display the image:
If you need to use a specific crop, you can inject the imageUrlGeneratorResource
resource. This has a getCropUrl(mediaPath, width, height, imageCropMode, animationProcessMode)
method:
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.
Alias: Umbraco.Tags
Returns: IEnumerable<string>
The Tags property editor allows you to add multiple tags to a node.
The Tag group setting provides a way to categorize your tags in groups. So for each category you will create a new instance of the Tags property editor and setup the unique category name for each instance. Whenever a tag is added to an instance of the tags property editor it's added to the tag group, which means it will appear in the Typeahead list when you start to add another tag. Only tags that belong to the specified group will be listed. If you have a "Frontend" group and a "Backend" group the tags from the "Frontend" group will only be listed if you're adding a tag to the Tags property editor configured with the "Frontend" group name and vice versa.
Data can be saved in either Comma-Separated Values (CSV) format or in JSON format. By default data is saved in JSON format. The difference between using CSV and JSON is that with JSON you can save a tag, which includes comma separated values.
There are built-in property value converters, which means you don't need to worry about writing them yourself or parse the JSON output when choosing "JSON" in the storage type field. Therefore the last code example on this page will work out of the box without further ado.
Whenever a tag has been added it will be visible in the typeahead when you start typing on other pages.
You can use the ContentService to create and update Umbraco content from c# code, when setting tags there is an extension method (SetTagsValue) on IContentBase that helps you set the value for a Tags property. Remember to add the using statement for Umbraco.Core.Models
to take advantage of it.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
More on working with Tags (query all of them) can be found at the UmbracoHelper reference page
Returns: Boolean
Toggle is a standard checkbox which saves either 0 or 1, depending on the checkbox being checked or not.
The Toggle property has a setting which allows you to set the default value of the checkbox, either checked (true) or unchecked (false).
It is also possible to define a label, that will be displayed next to the checkbox on the content.
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.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
How to use the TextBox property editors in Umbraco CMS.
Alias: Umbraco.Textbox
Returns: String
Textbox is an HTML input control for text. It can be configured to have a fixed character limit. The default maximum amount of characters is 512 unless it's specifically changed to a lower amount.
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.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.UserPicker
Returns: IPublishedContent
The user picker opens a panel to pick a specific user from the Users section. The value saved is of type IPublishedContent.
Getting the Value of the property will return the user ID - properties of the User can be accessed by referencing UserService.
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.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.TextArea
Returns: String
Textarea is an HTML textarea control for multiple lines of text. It can be configured to have a fixed character limit, as well as define how big the space for writing can be. By default, there is no character limit unless it's specifically set to a specific value like 200 for instance. If you don't specify the number of rows, 10 will be the amount of rows the textarea will be occupying, unless changed to a custom value.
See the example below to learn how a value can be added or changed programmatically to a Textarea property. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
Alias: Umbraco.BlockGrid
Returns: BlockGridModel
The Block Grid property editor enables editors to layout their content in the Umbraco backoffice. The content is made of Blocks that can contain different types of data.
When testing out the property editor, you can use a set of predefined Blocks. The option will only be possible when there are no other Data Types using the Block Grid property editor.
Create a new Data Type.
Select the Block Grid as the Property editor.
Install the "Sample Configuration".
4 Blocks will be added to the property, ready for testing.
The Block Grid property editor is configured via the Data Types backoffice interface.
To set up the Block Grid property editor, follow these steps:
Navigate to the Settings section in the Umbraco backoffice.
Right-click the Data Types folder.
Select Create -> New Data Type.
Select Block Grid from the list of available property editors.
You will see the configuration options for a Block Grid property editor as shown below:
The Data Type editor allows you to configure the following properties:
Blocks - Defines the Block Types available for use in the property. For more information, see Setup Block Types.
Amount - Sets the minimum and/or the maximum number of Blocks that should be allowed at the root of the layout.
Live editing mode - Enabling this option will allow you to see the changes as you are editing them.
Editor width - Overwrites the width of the property editor. This field takes any valid CSS value for "max-width". For example: 100% or 800px.
Grid Columns - Define the number of columns in your grid layout. The default is 12 columns.
Layout Stylesheet - Replaces the built-in Layout Stylesheet. Additionally, you can retrieve the default layout stylesheet to use as a base for your own inspiration or for writing your own stylesheet.
Create Button Label - Overwrites the label on the Create button.
Block Types are based on Element Types. These can be created beforehand or while setting up your Block Types.
Once you have added an Element Type as a Block Type on your Block Grid Data Type you have the option to configure it.
Examples and more details about configuring the Label property
Blocks can also be grouped. This is visible in the Block Catalogue and can also be used to allow a group of Blocks in an Area.
Each Block has a set of properties that are optional to configure. These are described below.
Customize the user experience for your content editors when they work with the Blocks in the Content section.
Label - Defines a label for the appearance of the Block in the editor. The label can use AngularJS template-string-syntax to display values of properties.
Label example: "My Block {{myPropertyAlias}}" will be shown as: "My Block FooBar".
You can also use more advanced expression using AngularJS filters, like {{myPropertyAlias | limitTo:100}}
or for a property using Richtext editor {{myPropertyAlias | ncRichText | truncate:true:100}}
. It is also possible to use properties from the Settings model by using {{$settings.propertyAlias}}
.
Get more tips on how to use AngularJS filters in Umbraco CMS from this community-made Umbraco AngularJS filter cheat sheet.
Content model - Presents the Element Type used as model for the Content section of this Block. This cannot be changed but you can open the Element Type to perform edits or view the properties available. Useful when writing your Label.
Settings model - Adds a Settings section to your Block based on a given Element Type. When selected you can open the Element Type or choose to remove the Settings section again.
Customize the Blocks size in the Grid. If you define multiple options, the Block becomes scalable.
By default, a Block takes up the available width.
A Block can be resized in two ways:
When a Block is placed in an Area, it will fit to the Areas width. Learn more about Areas.
A Block can have one or more Column Span options defined.
A Column Span option is used to define the width of a Block. With multiple Column Span options defined, the Content Editor can scale the Block to fit specific needs.
Additionally, Blocks can be configured to span rows, this enables one Block to be placed next to a few rows containing other Blocks.
Available column spans - Defines one or more columns, the Block spans across. For example: in a 12 columns grid, 6 columns is equivalent to half width. By enabling 6 columns and 12 columns, the Block can be scaled to either half width or full width.
Available row spans - Defines the amount of rows the Block spans across.
See the scaling blocks section of this article for an example of how scaling works.
These properties refer to how the Block is presented in the Block catalogue when editors choose which Blocks to use for their content.
Background color - Defines a background color to be displayed beneath the icon or thumbnail. Example: #424242
.
Icon color - Changes the color of the Element Type icon. Example: #242424
.
Thumbnail - Pick an image or Scalable Vector Graphics (SVG) file to replace the icon of the Block in the catalogue.
The thumbnails for the catalogue are presented in the format of 16:10. We recommend a resolution of 400px width and 250px height.
Allow in root - Determines whether the Block can be created at the root of your layout. Turn this off if you only want a Block to appear within Block Areas.
Allow in areas - Determines whether the Block can be created inside Areas of other Blocks. If this is turned off it can still be allowed in Block Areas by defining specific allowed Blocks.
Blocks can nest other Blocks to support specific compositions. These compositions can be used as a layout for other Blocks.
To achieve nesting, a Block must have one or more Areas defined. Each Area can contain one or more Blocks.
Each Area has a size, defined by column and rows spans. The grid for the Areas are based on the same amount of columns as your root grid, unless you choose to change it.
To scale an Area, click and drag the scale-button in the bottom-right corner of an Area.
Grid Columns for Areas - Overwrites the amount of columns used for the Area grid.
Areas - Determines whether the Block can be created inside Areas of other Blocks.
Alias - The alias is used to identify this Area. It is being printed by GetBlockGridHTML()
and used as name for the Area slot in Custom Views. The alias is also available for CSS Selectors to target the HTML-Element representing an Area.
Create Button Label - Overwrites the Create Button Label of the Area.
Number of blocks - Determines the total number of Blocks in an Area.
Allowed block types - When this is empty, all Blocks with Permissions for creation in Areas, will be available. This can be overwritten by specifying the allowed Blocks. Define the types of Blocks or Groups of Blocks that are allowed. Additionally, you can also set how many Blocks of each type/group should be present.
When allowing a Group of Blocks, you might want to require a specific amount for a certain Block of that Group. This can be done by adding that Block Type to the list as well and set the requirements.
These properties are relevant when working with custom views or complex projects.
Custom view - Overwrites the AngularJS view for the block presentation in the Content editor. Use this view to make a more visual presentation of the Block or make your own editing experience by adding your own AngularJS controller to the view.
Notice that any styling of a Block is scoped. This means that the default backoffice styles are not present for the view of this Block.
Custom stylesheet - Pick your own stylesheet to be used by the Block in the Content editor.
Overlay editor size - Sets the size for the Content editor overlay for editing this block.
Hide content editor - Hides the UI for editing the content in a Block Editor. This is only relevant if you made a custom view that provides the UI for editing of content.
When viewing a Block Grid property editor in the Content section for the first time, you will be presented with the option to Add content.
Clicking the Add content button opens up the Block Catalogue.
The Block Catalogue looks different depending on the amount of available Blocks and their catalogue appearance.
Click the Block Type you wish to create and a new Block will appear in the layout.
More Blocks can be added to the layout by clicking the Add content button. Alternatively, use the Add content button that appears on hover to add new Blocks between, besides, or above the existing Blocks.
To delete a Block, click the trash icon which appears on the mouse hover.
Blocks can be rearranged using the click and drag feature. Move them up or down to place them in the desired order.
Moving a Block from one Area to another is done in the same way. If a Block is not allowed in the given position, the area will display a red color and not allow the new position.
If a Block has multiple size options it can be scaled via the UI. This appears in the bottom left corner of the Block.
The Block is resized using a click-and-drag feature. Moving the mouse will change the size to the size options closest to the mouse pointer.
Rendering the stored value of your Block Grid property editor can be done in two ways:
You can choose to use the built-in rendering mechanism for rendering Blocks using a Partial View for each block.
The default rendering method is named GetBlockGridHtmlAsync()
and comes with a few options - for example:
In the sample above "myGrid"
is the alias of the Block Grid editor.
If you are using ModelsBuilder, the example will look like this:
To use the GetBlockGridHtmlAsync()
method, you will need to create a Partial View for each Block Type. The Partial View must be named using the alias of the Element Type that is being used as Content Model for the Block Type.
These Partial View files need to go into the Views/Partials/blockgrid/Components/
folder.
Example: Views/Partials/blockgrid/Components/MyElementTypeAliasOfContent.cshtml
.
The Partial Views will receive a model of type Umbraco.Cms.Core.Models.Blocks.BlockGridItem
. This model contains Content
and Settings
from your block, as well as the configured RowSpan
, ColumnSpan
, and Areas
of the Block.
The Partial View for the Block is responsible for rendering its own Block Areas. This is done using another built-in rendering mechanism:
Here you will need to create a Partial View for each Block Type within the Block Area. For the name, use the alias of the Element Type that is being used as Content Model for the Block Type.
These Partial Views must be placed in the same folder as before, (Views/Partials/blockgrid/Components/
), and will receive a model of type Umbraco.Cms.Core.Models.Blocks.BlockGridItem
.
The following is an example of a Partial View for a Block Type of type MyElementTypeAliasOfContent
.
If you are using ModelsBuilder, you can make the property rendering strongly typed by letting your view accept a model of type BlockGridItem<T>
. For example:
Using the default rendering together with your layout stylesheet will provide what you need for rendering the layout.
If you like to use the Default Layout Stylesheet, you must copy the stylesheet to your frontend. You can download the default layout stylesheet from the link within the DataType, we recommend putting the file in the css folder, example: wwwroot/css/umbraco-blockgridlayout.css
.
A set of built-in Partial Views are responsible for rendering the Blocks and Areas in a grid layout. If you want to tweak or change the way the grid layout is rendered, you can use the built-in Partial Views as a template:
Clone the views from <a href="https://github.com/umbraco/Umbraco-CMS/">GitHub</a>
. They can be found in /src/Umbraco.Cms.StaticAssets/Views/Partials/blockgrid/
Copy the cloned views to the local folder Views/Partials/blockgrid/
Make changes to your copied views. The entry point for GetBlockGridHtmlAsync()
is the view default.cshtml
The built-in value converter for the Block Grid property editor lets you use the block data as you like. Call the Value<T>
method with a type of BlockGridModel
to have the stored value returned as a BlockGridModel
instance.
BlockGridModel
contains the Block Grid configuration (like the number of columns as GridColumns
) whilst also being an implementation of IEnumerable<BlockGridItem>
(see details for BlockGridItem
above).
The following example mimics the built-in rendering mechanism for rendering Blocks using Partial Views:
If you do not want to use Partial Views, you can access the block item data directly within your rendering:
The default layout stylesheet is using CSS Grid. This can be modified to fit your implementation and your project.
To make additions or overwrite parts of the default layout stylesheet, import the default stylesheet at the top of your own file.
You need to copy the Default Layout Stylesheet to your frontend. You can download the default layout stylesheet from the link within the DataType, we recommend putting the file in the css folder, example: wwwroot/css/umbraco-blockgridlayout.css
.
In this case, you would have to write the layout from scratch.
You are free to pick any style, meaning there is no requirement to use CSS Grid. It is, however, recommended to use CSS Grid to ensure complete compatibility with the Umbraco backoffice.
When extending or writing your own layout, you need to know the structure and what data is available.
For example: You can use the below HTML structure:
Building Custom Views for Block representations in Backoffice is based on the same API for all Block Editors.
Read about building a Custom View for Blocks here
In this example, we will be creating content programmatically for a "spot" Blocks in a Block Grid.
On a document type add a property called blockGrid.
Then add as editor Block Grid.
In the Block Grid add a new block and click to Create new Element Type
Name this element type spotElement with the following properties:
a property called title with the editor of Textstring
a property called text with the editor of Textstring
Then on the Settings model click to add a new Setting.
Then click to Create new Element Type.
Name this element type spotSettings with the following properties:
a property called featured with the editor of True/false.
The raw input data for the spots looks like this:
The resulting JSON object stored for the Block Grid will look like this:
For each item in the raw data, we need to create:
One contentData
entry with the title and text.
One settingsData
entry with the featured value (the checkbox expects "0"
or "1"
as data value).
One layout
entry with the desired column and row spans.
All contentData
and layoutData
entries need their own unique Udi
as well as the ID (key) of their corresponding Element Types. In this sample, we only have one Element Type for content (spotElement
) and one for settings (spotSettings
). In a real life scenario, there could be any number of Element Type combinations.
First and foremost, we need models to transform the raw data into Block Grid compatible JSON. Create a class called Model.cs containing the following:
By injecting ContentService and ContentTypeService into an API controller, we can transform the raw data into Block Grid JSON. It can then be saved to the target content item. Create a class called BlockGridTestController.cs containing the following:
For the above code IContent? content = _contentService.GetById(1203);
change the id with your content node that is using the Block Grid.
In order to test this implementation, run the project and add /umbraco/api/blockgridtest/create
after your domain name. If the result shows as Saved then check your content node and you will see the 2 spotElement contents.
This can also be tested via Postman as well if preffered.
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.
Alias: Umbraco.BlockList
Returns: IEnumerable<BlockListItem>
Block List is a list editing property editor, using Element Types to define the list item schema.
The Block List replaces the obsolete Nested Content editor.
The Block List property editor is configured in the same way as any standard property editor, via the Data Types admin interface.
To set up your Block List Editor property, create a new Data Type and select Block List from the list of available property editors.
Then you will see the configuration options for a Block List as shown below.
The Data Type editor allows you to configure the following properties:
Available Blocks - Here you will define the Block Types to be available for use in the property. Read more on how to set up Block Types below.
Amount - Sets the minimum and/or maximum number of blocks that should be allowed in the list.
Single block mode - When in Single block mode, the output will be BlockListItem<>
instead of BlockListModel
Live editing mode - Enabling this will make editing of a block happening directly to the document model, making changes appear as you type.
Inline editing mode - Enabling this will change editing experience to inline, meaning that editing the data of blocks happens at sight as accordions.
Property editor width - Overwrite the width of the property editor. This field takes any valid css value for "max-width".
Block Types are Element Types which need to be created before you can start configuring them as Block Types. This can be done either directly from the property editor setup process, or you can set them up beforehand and add them to the block list after.
Once you have added an element type as a Block Type on your Block List Data Type you will have the option to configure it further.
Each Block has a set of properties that are optional to configure. They are described below.
By configuring the properties in the group you can customize the user experience for your content editors when they work with the blocks in the Content section.
Label - Define a label for the appearance of the Block in the editor. The label can use AngularJS template string syntax to display values of properties. Examples and more details about labels and AngularJS templates.
Custom view - Overwrite the AngularJS view for the block presentation in the Content editor. Use this to make a more visual presentation of the block or even make your own editing experience by adding your own AngularJS controller to the view.
Custom stylesheet - Pick your own stylesheet to be used for this block in the Content editor. By adding a stylesheet the styling of this block will become scoped. Meaning that backoffice styles are no longer present for the view of this block.
Overlay editor size - Set the size for the Content editor overlay for editing this block.
It is possible to use two separate Element Types for your Block Types. Its required to have one for Content and optional to add one for Settings.
Content model - This presents the Element Type used as model for the content section of this Block. This cannot be changed, but you can open the Element Type to perform edits or view the properties available. Useful when writing your Label.
Settings model - Add a Settings section to your Block based on a given Element Type. When picked you can open the Element Type or choose to remove the settings section again.
These properties refer to how the Block is presented in the Block catalogue, when editors choose which Blocks to use for their content.
Background color - Define a background color to be displayed beneath the icon or thumbnail. Eg. #424242
.
Icon color - Change the color of the Element Type icon. Eg. #242424
.
Thumbnail - Pick an image or SVG file to replace the icon of this Block in the catalogue.
The thumbnails for the catalogue are presented in the format of 16:10, and we recommend a resolution of 400px width and 250px height.
These properties are relevant when you work with custom views.
Force hide content editor - If you made a custom view that enables you to edit the content part of a block and you are using default editing mode (not inline) you might want to hide the content-editor from the block editor overlay.
When viewing a Block List editor in the Content section for the first time, you will be presented with the option to Add content.
Clicking the Add content button brings up the Block Catalogue.
The Block Catalogue looks different depending on the amount of available Blocks and their catalogue appearance.
Click the Block Type you wish to create and a new Block will appear in the list.
Depending on whether your Block List Editor is setup to use default or inline editing mode you will see one of the following things happening:
In default mode you will enter the editing overlay of that Block:
In inline editing mode the new Blocks will expand to show its inline editor:
More Blocks can be added to the list by clicking the Add content button or using the inline Add content button that appears on hover between or above existing Blocks.
To reorder the Blocks, click and drag a Block up or down to place in the desired order.
To delete a Block click the trash-bin icon appearing on hover.
Rendering the stored value of your Block List property can be done in two ways.
You can choose to use the built-in rendering mechanism for rendering blocks via a Partial View for each block.
The default rendering method is named GetBlockListHtml()
and comes with a few options to go with it. The typical use could be:
"MyBlocks" above is the alias for the Block List editor.
If using ModelsBuilder the example can be simplified:
Example:
To make this work you will need to create a Partial View for each block, named by the alias of the Element Type that is being used as Content Model.
These partial views must be placed in this folder: Views/Partials/BlockList/Components/
. Example: Views/Partials/BlockList/Components/MyElementTypeAliasOfContent.cshtml
.
A Partial View will receive the model of Umbraco.Core.Models.Blocks.BlockListItem
. This gives you the option to access properties of the Content and Settings section of your Block.
In the following example of a Partial view for a Block Type, please note that the MyElementTypeAliasOfContent
and MyElementTypeAliasOfSettings
should correspond with the selected Element Type Alias for the given model in your case.
Example:
With ModelsBuilder:
A built-in value converter is available to use the data as you like. Call the Value<T>
method with a generic type of IEnumerable<BlockListItem>
and the stored value will be returned as a list of BlockListItem
entities.
Example:
Each item is a BlockListItem
entity that contains two main properties Content
and Settings
. Each of these is a IPublishedElement
which means you can use all the value converters you are used to using.
Example:
In some cases, you might want to use the Block List Editor to hold some data and not necessarily render a view since the data should be presented in different areas on a page. An example could be a product page with variants stored in a Block List Editor.
In this case, you can extract the variant's data using the following, which returns IEnumerable<IPublishedElement>
.
Example:
If using ModelsBuilder the example can be simplified:
Example:
If you know the Block List Editor only uses a single block, you can cast the collection to a specific type T
using .OfType<T>()
otherwise the return value will be IEnumerable<IPublishedElement>
.
Building Custom Views for Block representations in Backoffice is the same for all Block Editors. Read about building a Custom View for Blocks here
We highly recommend that you use the Block Grid 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.
When configuring a block, the label property allows you to define a label for the appearance of the Block in the editor. The label can use AngularJS template string syntax to display values of properties. Example: My Block {{myPropertyAlias}}
will be shown as: My Block FooBar
.
You can also use more advanced expressions using AngularJS filters. Example: {{myPropertyAlias | limitTo:100}}
or for a property using the Richtext editor {{myPropertyAlias | ncRichText | truncate:true:100}}
.
It is also possible to use properties from the settings model by using {{$settings.propertyAlias}}
.
In some cases, you might want to create a fallback label. This can be achieved using the following format: {{myProperty || $contentTypeName}}
.
This example will show the name of the ElementType when the value of myProperty
is not defined.
As well as the default AngularJS filters, Umbraco ships with additional filters which are useful for setting the Label field of Block editors.
Filter | Description | Property type | Parameters |
---|---|---|---|
This is how you could use the filter for a Media Picker of the type Umbraco.MediaPicker3
with multiple images:
The mediaKey
is a Guid like c7a4526c-6b32-4665-a047-5b3e7256d973
.
For the Media Name, the same could be achieved using ncNodeName
like shown below:
The ncNodeName
value expects a UDI like umb://media/c7a4526c6b324665a0475b3e7256d973
.
If the filters do not suit your needs, you can create custom filters by creating a plugin in App_Plugins
and adding a filter module. You can see an example below:
If you do not have an /App_Plugins
folder, you can create it at the root of your project.
Create a plugin by adding a folder inside App_Plugins
called MyFilters
Inside the MyFilters
folder add a package.manifest
file containing:
Add a myFilter.filter.js
file containing:
Implement a block editor of your choice. When adding a label add {{ myFilter }}
which is the property alias of the element type. The myFilter
property has a textstring
editor. When adding the content, the block editor will then display the data that you input.
Alias: Umbraco.DropDown.Flexible
Returns: String
or IEnumerable<string>
Displays a list of preset values. Either a single value or multiple values (formatted as a collection of strings) can be returned.
If enabled, editors will be able to select multiple values from the dropdown otherwise only a single value can be selected.
Prevalues are the options which are shown in the dropdown list. You can add, edit, or remove values here.
You can use dictionary items to translate the values of a Dropdown property editor in a multilingual setup. For more details, see the Creating a Multilingual Site article.
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.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
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:
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.
Alias: Umbraco.TinyMCE
Returns: HTML
The Rich Text Editor (RTE) is based on and is highly configurable. Depending on the configuration, it will give your content editors more flexibility when working with content that should be more than only plain text.
Are you using custom configuration or plugins with TinyMCE?
In Umbraco 11 the TinyMCE version supported has been upgraded from version 4 to version 6. You need to migrate to the latest version if you are using TinyMCE plugins or custom configuration.
If your site is upgraded from an older version, follow the migration guides below to upgrade the TinyMCE version as well.
Customize everything from toolbar options to editor size to where pasted images are saved.
Use CSS to define specific editor styles and add them as formatting options of the Rich Text Editor.
Use Blocks to define specific parts which can be added as part of the markup of the Rich Text Editor.
Extend the functionality of the Rich Text Editor with plugins.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
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:
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:
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.
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.
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.
Variable | Description |
---|---|
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 .
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 .
You can read more about package.manifest
files in general at the page.
ncNodeName
Gets the name of a node
Umbraco node
ncRichText
Strips HTML
Richtext editor
mediaItemResolver
Retrieves a Media Item object
Media Picker
AngularJS native truncate
String
n: maximum length of the string
Umbraco's richer truncate function
String
wordwise: boolean to indicate whether to truncate a string mid-word or not
max: maximum length of the string
tail (optional): string to indicate a truncated string, "…
" by default
Truncates to a number of words (rather than characters)
String
n: maximum number of words in string
Converts a string to title case
String
Joins an array into one string
Array (of string or object)
separator: string used to join values together, e.g. ",
"
prop (optional): string key indicating which property to join when used on an array of objects
$index
The 1-based index of this block item in the current block list
$contentTypeName
The name of the Element Type used for the Block
$settings
Provides access to the settings model for the block (if configured)
$layout
Provides access to the layout model for the block (columnSpan and rowSpan)
A guide displaying the options available in the Settings section in Umbraco CMS backoffice.
The Settings section of the Umbraco backoffice has its own set of default dashboards. In this article, you can get an overview of each dashboard available in the Settings section:
Information on using the Umbraco log viewer
Umbraco ships with a built-in Log Viewer feature. This allows you to filter and view log entries and perform much more complex search queries. This helps you find the log entries that you are interested in. You can find the Log viewer in the Settings section.
Have you ever wanted to find all log entries which contain the same request ID? Or find all items in the log where a property called duration is greater than 1000ms?
With the power of structured logging and a query language, we are able to search and find log items for specific scenarios. When debugging the site you should now have more power to see and find patterns in your log files and get rid of those errors.
Here are a handful of example queries to get you started, however, the saved searches contain some further examples. For more details on the syntax head over to the https://github.com/serilog/serilog-filters-expressions project.
Find all logs that are from the namespace 'Umbraco.Core'
StartsWith(SourceContext, 'Umbraco.Core')
\
Find all logs that have the property 'Duration' and the duration is greater than 1000ms
Has(Duration) and Duration > 1000
\
Find all logs where the message has localhost in it with SQL like
@Message like '%localhost%'
\
Sometimes you want to use a custom query more often. It is possible to save a query and use the dropdown to re-use your saved search. To add a new saved search, use the search box to type your query and click the star icon. In doing so you can give it a friendly name. The saved queries are saved in the database in the table umbracoLogViewerQuery
.
With the flexibility of Umbraco, we give you the power to implement your own ILogViewer
. This makes it possible to fetch logs and the saved searches from a different location such as Azure table storage.
To do this we can implement a base class SerilogLogViewerSourceBase
from Umbraco.Cms.Core.Logging.Viewer
like so.
This uses the Azure.Data.Tables
NuGet package.
Keep in mind that we have to implement our own version of a LogEventEntity
. This is because the TableClient
needs whatever it is fetching to implement the ITableEntity
interface.
Umbraco needs to be made aware that there is a new implementation of an ILogViewer
to register. We also need to replace the default JSON LogViewer that we ship in the core of Umbraco.
Now with the above two classes, we have the plumbing in place to view logs from an Azure Table. However, we are not persisting our logs into the Azure table storage account. So we need to configure the Serilog logging pipeline to store our logs in Azure table storage.
Install Serilog.Sinks.AzureTableStorage from Nuget
Add a new sink to the appsettings with credentials (so logs persist to Azure)
The following sink needs to be added to the array Serilog:WriteTo
.
For more in-depth information about logging and how to configure it, please read the logging documentation.
This is a desktop tool for viewing & querying JSON log files from disk in the same way as the built-in logviewer dashboard of Umbraco.
Information on how to work with TinyMCE plugins in the rich text editor.
The global configuration of TinyMCE will be removed in Umbraco 14 in order to support more rich text editors in the future. Instead, a new extension type called “tinyMcePlugin” will be added.
The Rich Text Editor (RTE) in Umbraco is based on the open source editor TinyMCE. TinyMCE is a highly customizable editor, and it is possible to extend the functionality of the editor by adding plugins.
TinyMCE comes with a lot of plugins out of the box, but it is also possible to create your own plugins. This article will show you how to add a custom plugin to the rich text editor.
TinyMCE has a lot of open-source plugins available. You can find a list of these plugins on the TinyMCE website.
TinyMCE also has a number of premium plugins available. These plugins are only available for paid TinyMCE subscriptions.
To enable plugins in the rich text editor, you need to add it to the Plugins
array in the configuration of the rich text editor.
The example above shows how to add the open-source Word Count Plugin to the rich text editor. The plugin is added to the Plugins
array in the configuration. The plugin itself will be shown in the statusbar of the rich text editor, so the statusbar
option is also added to the CustomConfig
object.
To add a premium plugin, you need to add the plugin name to the Plugins
array in the configuration of the rich text editor. You also need to add the "CloudApiKey" to the configuration.
We have enabled the powerpaste
plugin, and configured it to allow local images. It will prompt when pasting Word documents, but for HTML documents it will clean the HTML without prompting.
See all the available premium plugins.
You can go to TinyMCE Cloud and sign up for a free trial. You will get a Cloud API key that you can use to try out the premium plugins.
If you want to create your own plugin, you should in general follow the TinyMCE documentation. However, there are a few things you need to be aware of to load the plugin in Umbraco. See the example below.
Load a custom plugin that gives you the ability to interact with the global tinymce
editor object.
Here we are loading a custom plugin called myrteplugin
and adding a button to the editor called myrtebutton
. When the button is clicked, it will insert the text Hello World!
into the editor.
The button must be added to the toolbar in the rich text editor configuration.
You can go to any Document Type that uses the rich text editor and click the button to insert the text Hello World!
after.
In this article you can learn about how to create and use Content Templates in Umbraco.
Content Templates allows a content editor to create a blueprint for new content nodes based on an existing node.
Before following this method you should have some content created beforehand.
Select a Content node from the Content menu:
Right-click the Content node and select the Create Content Template option. Alternatively, select the Actions dropdown of the content node and select the Create Content Template option:
Give your content template a Name:
Click the Create button and if the creation was successful, you will see a success notification:
The new content template will be created in Content Templates node of the Settings tree:
Refresh your browser, if you do not see the new content template in the Content Templates folder.
Click on the Settings menu:
Right-click on the Content Templates tree and select the Create menu item:
Select the Document Type you want to create a content template for:
You can create content templates only from Document Types or Document Types with Templates
Give your content template a Name and click the Save button:
The new content template will be created in Content Templates folder of the Settings tree:
To edit an existing content template, select a content template from the Content Templates folder of the Settings tree. When you have finished editing click the Save button:
Once you have created a content template, you can use the template to create new content nodes. To use a content template, right-click the Content tree and select Create:
When you click on a Document Type that has a content template you will see two options:
Create a new node based on a content template
Create a blank one
Learn how to use language variants to output your content in multiple languages.
Language Variants allows you to vary content by culture, so you can allow a content node to exist in multiple languages.
This article will cover the different aspects of enabling and working with language variants on your Umbraco website.
To work with Language Variants you need to have more than one language enabled. This can be done from the Settings
section:
You will always have one default language but each language can be set to mandatory.
Now that there are two languages to vary the content with, it needs to be enabled on the Document Types. To do so:
Go to the Document Type in the Settings section.
Open the Permissions page.
Toggle Allow vary by culture.
To allow a property on the Document Type to be varied it will have to be enabled for the property:
When you return to your content node you will notice two things:
At the top of the Content tree there will now be a dropdown so you can show the Content tree in the language of your choice.
To the right of the content name there is now a dropdown where you can select a language. You can also open a split view so you can see two languages at once.
Each Property Editor that does not allow variants (an Invariant Property) will by default need to be unlocked in order to be edited. The lock exists to make it clear that this change will affect more languages. Since the value of the invariant properties are shared between all variants on the website.
Whether or not the lock is enabled on the invariant properties depends on the AllowEditInvariantFromNonDefault
setting in the appsettings.json
file.
For projects created on Umbraco version 10.2 or later, the setting is true
, by default. If the project is upgraded to version 10.2 or later, the setting will by default be false
.
Learn more about the AllowEditInvariantFromNonDefault
setting in the Security Settings article.
To read about how you render variant content in Templates, check out the rendering content section.
Culture and hostnames must be added to your language sites before the content can be tested for variants:
Right-click the Home node and select Culture and hostnames....
Add a specific URL per language and save. For eg: An English language variant with English (United States) as the language can be given a specific URL https://yourwebsite.com/en-us and a Danish language variant can be given a specific URL https://yourwebsite.com/dk.
The Info content app should now show specific URLs for your language variants.
This feature is available from Umbraco version 10.2.
When you are working with a multilingual site you might want to control who can edit the different variations of the content on the website.
This can be controlled on a User Group level. All default User Groups, except the Sensitive data group, have access to all languages out of the box.
When "Allow access to all languages" is not checked, languages can be added and/or removed. This is to determine which variants the users in the user group have access to.
Even though the language permissions have been set, a user will still be able to view and browse all the language variations. The permission setting will ensure that only the added languages are editable by users of the User Group.
It is possible to insert Blocks into the markup of the Rich Text Editor (RTE). Once you've defined the Block Type as part of the RTE Data Type and enabled the Blocks Toolbar Option. Then Blocks can be created directly inside the Rich Text Editor.
The Block List property editor is configured in the same way as any standard property editor, via the Data Types admin interface.
To set up your Block List Editor property, create a new Data Type and select Block List from the list of available property editors.
Then you will see the configuration options for a Block List as shown below.
The Data Type editor allows you to configure the following properties:
Available Blocks - Here you will define the Block Types to be available for use in the property. Read more on how to set up Block Types below.
Blocks Live editing mode - Enabling this will make editing of a Block happen directly to the Rich Text Editor, making changes appear as you type.
Block Types are Element Types that need to be created before you can start configuring them as Block Types. This can be done either directly from the property editor setup process, or you can set them up beforehand. If they are set beforehand then they need to be added to the Rich Text Editor afterward.
Once you add an Element Type as a Block Type on your Rich Text Editor Data Type you will have options to configure it further.
Each Block has a set of properties that are optional to configure. They are described below.
By configuring the properties in the group you can customize the user experience for your content editors when they work with the blocks in the Content section.
Label - Define a label for the appearance of the Block in the editor. The label can use AngularJS template string syntax to display values of properties. Examples and more details about labels and AngularJS templates.
Display Inline with text - When turned on the Block Element will be able to stay in line with text or other elements. If not the Block will stay on its own line.
Custom view - Overwrite the AngularJS view for the block presentation in the Content editor. Use this to make a more visual presentation of the block or even make your own editing experience by adding your own AngularJS controller to the view.
Custom stylesheet - Pick your own stylesheet to be used for this block in the Content editor. By adding a stylesheet the styling of this block will become scoped. Meaning that backoffice styles are no longer present for the view of this block.
Overlay editor size - Set the size for the Content editor overlay for editing this block.
It is possible to use two separate Element Types for your Block Types. It's required to have one for Content and optional to add one for Settings.
Content model - This presents the Element Type used as a model for the content section of this Block. This cannot be changed, but you can open the Element Type to perform edits or view the properties available. Useful when writing your Label.
Settings model - Add a Settings section to your Block based on a given Element Type. When picked you can open the Element Type or choose to remove the settings section again.
These properties refer to how the Block is presented in the Block catalog when editors choose which Blocks to use for their content.
Background color - Define a background color to be displayed beneath the icon or thumbnail. Eg. #424242
.
Icon Color - Change the color of the Element Type icon. Eg. #242424
.
Thumbnail - Pick an image or Scalable Vector Graphics (SVG) file to replace the icon of this Block in the catalog.
The thumbnails for the catalog are presented in the format of 16:10, and we recommend a resolution of 400px width and 250px height.
These properties are relevant when you work with custom views.
Force hide content editor - If you made a custom view that enables you to edit the content part of a block and you are using default editing mode (not inline) you might want to hide the content editor from the block editor overlay.
To render Blocks in the frontend, you must create Partial Views for each Block.
The Partial Views must be:
Named by the alias of the Element Type that is being used as the Content Model for the Block.
Placed in the folder Views/Partials/RichText/Components/
.
For example, if the Element Type alias of the Content Model is myBlockType
, a Partial View must be created at Views/Partials/RichText/Components/MyBlockType.cshtml
.
The Partial View will receive the model of Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem
. This gives you the option to access properties of the Content and Settings Models of your Block, as illustrated in the following sample:
If you use ModelsBuilder, you can specify the Content Model (and optionally the Settings Model) in the Partial View model. This allows for type-safe access to the Block data.
The following example shows a Partial View of a Block with MyBlockType
as Content Model and MyBlockSettingsType
as Settings Model:
Building Custom Views for Block representations in Backoffice is the same for all Block Editors. Read about building a Custom View for Blocks here
It is possible to define specific styles and fonts for the Rich Text Editor (RTE). Once you have defined the styles, and enabled them on the RTE Data Type, the styles can be accessed directly in the Content section.
The RTE styles are created and managed in the Umbraco backoffice.
Find the Stylesheets folder in the Settings section.
Right-click the folder and select Create....
Choose New Rich Text Editor style sheet file.
Give the new stylesheet a name and Save it.
This will generate an empty CSS file in your project.
At this point, you can start adding specific styles, that your editors can then use in the Content section when creating and writing new content.
The image above is an example of how an RTE style can be configured. When working with these styles, the Preview feature will show you how the style will look when applied.
Every style you add, will automatically be added to the CSS file. The file will be placed in the same location as the rest of your CSS files. It is possible to edit the file directly from the backoffice as well. Access it from the Code tab in the top-right corner.
In order for your editors to be able to use the styles when working with content, two things needs to be done.
The styles will be accessed by the editors using the "Formats" dropdown in the toolbar of the RTE. In order the enable the dropdown, the "Style select" toolbar option needs to be checked.
This can be done by accessing the RTE Data Type directly from the "Info" tab on the Content. You can also find the RTE Data Type in the Settings section of the backoffice and make the changes from there. Learn more about the configuration options in the RTE Config article.
You can have as many different styles for your RTEs as you want. You might want to have different styles for different RTE Data Types.
When configuring your RTE Data Types, you can select which stylesheets your content editors should be able to use.
In this article you can learn about the various ways you can configure the RTE.
You have full control over which options should be available on the RTE.
In the examble above, all 34 options have been enabled. The options include copy/paste buttons, font styles like bold and italics, bullet lists and options to embed videos and insert images.
It is possible to define specific styles that can be used when editing content using the RTE. You can use as many of these styles with the RTE as you want.
The RTE styles are defined in CSS files which can be created in the Settings section. Read the RTE Styles article to learn more about this feature.
Define height
and width
of the editor displayed in the content section.
Define the maximum size for images added through the Rich Text Editor.
If inserted images are larger than the dimensions defined here, the images will be resized automatically.
The Rich Text Editor comes in two different modes: Classic and Inline.
The default mode which displays the toolbar at the top.
In this mode the toolbar is hidden, and only shows up when content in the editor is highlighted.
Blocks can be added as elements in the Rich Text Editor. Configuration and rendering of Blocks is described in the Blocks in Rich Text Editor article.
Select the width of the link picker overlay. The overlay size comes in three sizes: Small, Medium, and Large.
When this option is checked the label and description for the RTE property will be hidden.
Some of the backoffice users might be restricted to a specific part of the content tree. When the "Ignore User Start Nodes" is checked, the users can pick any piece of content from the content tree, when adding internal links through the RTE.
Images added through the RTE is by default added to the root of the Media library.
Sometimes you might want to add the images to a specific folder. This folder can be configured using the "Image Upload Folder" setting.
The global configuration of RichTextEditor will be removed in Umbraco 14 to support more rich text editors in the future. Instead, a new extension type called “tinyMcePlugin” will be added.
The RTE can also accept advanced configuration through the appSettings.json
file fed into the TinyMCE configuration. This is within Umbraco:CMS:RichTextEditor
and allows you to configure the following:
CustomConfig
is slightly different from the rest as it extends the core config passed into TinyMCE.
Read more about the advanced configuration and how to set it up in Umbraco in the Rich Text Editor Settings article.
Sometimes you want to allow your content editors to be able to add <script>
tags into the RTE. This tag is classed as invalid by default which means the configuration needs to be updated to allow it. This is not something that can be done through the CMS and requires advanced configuration in the appSettings.json
file. It uses the ValidElements
property to append ,script[*]
to the pre-existing list of valid elements as shown below.
This section explains how the concept of infinite editing in the Umbraco backoffice works.
This feature enables you to work with your content without losing the context of what you are doing.
Document Types are in different sections than content but infinite editing enables you to make changes to them directly from the content you are editing.
In the example showcased above, prevalues are being added to a Data Type, without losing the context of the content that's being worked on. The example also shows how you can edit images, without being sent to the 'Media' section.
Infinite editing is a feature that comes out of the box with Umbraco. The feature can be customized, which enables you as a developer to improve the workflow for your editors.
In this article you can learn the various ways of customizing the Umbraco backoffice login screen and form.
To access the backoffice, you will need to login. You can do this by adding /umbraco
at the end of your website URL, for example http://mywebsite.com/umbraco.
You will be presented with a login form similar to this:
The login screen contains a Greeting, Email, Password field and optionally a Forgotten password link
Below, you will find instructions on how to customize the login screen.
The login screen features a greeting which you can personalize by overriding the existing language translation keys. To do this, create a 'user' translation file for the default language of your Umbraco site, (usually en-US) to override the greetings. For en-US, you'd create a file called: en_us.user.xml
in the directory ~/config/lang/
. Then take the relevant keys (listed below) and add them to your ~/config/lang/en_us.user.xml
file, and update the greetings as necessary.
Note: the config
directory needs to be in the root of your project (not the wwwroot
).
Before the changes takes place you will need to restart the site.
You can customize other text on the login screen as well. First, grab the default values and keys from the en_us.xml in the Umbraco CMS Github repository. Thereafter copy the ones you want to translate into ~/config/lang/en_us.user.xml
file.
The Forgotten password? link allows your backoffice users to reset their password. To use this feature, you will need to add the following key to the Umbraco.Cms.Security
section in the appsettings.json
file:
Set it to true
to enable the password reset feature, and false
to disable the feature.
You will also need to configure a Simple Mail Transfer Protocol (SMTP) server in your appsettings.json
file. When you get a successful result on the SMTP configuration when running a health check in the backoffice, you are good to go!
An example:
It is possible to customize the background image and the logo for the backoffice login screen by adding the "Content"
section in the appsettings.json
file:
The LoginBackgroundImage
, LoginLogoImage
, and LoginLogoImageAlternative
are referenced from the /wwwroot/umbraco/
folder.
The LoginLogoImage
is displayed on top of the LoginBackgroundImage
and the LoginLogoImageAlternative
is displayed when the LoginLogoImage
is not available, for example on small resolutions.
You can also customize the login screen by adding a custom CSS file. To do this, you will need to add a new file inside the ~/App_Plugins
folder, for example ~/App_Plugins/MyCustomLoginScreen/my-custom-login-screen.css
.
You can then add your custom CSS to the file:
This will change the color of the SVG graphics (curves) shown on the login screen. You can also hide the curves by adding the following CSS:
To tell Umbraco about your custom CSS file, you will need to add a package.manifest
file. The package.manifest
file should look like this:
The following CSS properties are available for customization:
The CSS custom properties may change in future versions of Umbraco. You can always find the latest values in the login layout element in the Umbraco CMS Github repository.
CSS Property | Description | Default Value |
---|---|---|
--umb-login-background
The background of the layout
#f4f4f4
--umb-login-primary-color
The color of the headline
#283a97
--umb-login-text-color
The color of the text
#000
--umb-login-header-font-size
The font-size of the headline
3rem
--umb-login-header-font-size-large
The font-size of the headline on large screens
4rem
--umb-login-header-secondary-font-size
The font-size of the secondary headline
2.4rem
--umb-login-image
The background of the image wrapper
The value of the LoginBackgroundImage setting
--umb-login-image-display
The display of the image wrapper
flex
--umb-login-image-border-radius
The border-radius of the image wrapper
38px
--umb-login-content-background
The background of the content wrapper
none
--umb-login-content-display
The display of the content wrapper
flex
--umb-login-content-width
The width of the content wrapper
100%
--umb-login-content-height
The height of the content wrapper
100%
--umb-login-content-border-radius
The border-radius of the content wrapper
0
--umb-login-align-items
The align-items of the main wrapper
unset
--umb-login-button-border-radius
The border-radius of the buttons
45px
--umb-login-curves-color
The color of the curves
#f5c1bc
--umb-login-curves-display
The display of the curves
inline