Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This section focuses on how to create data using the Umbraco backoffice
This section focuses on how to create data using the Umbraco backoffice.
There are three kinds of content in Umbraco:
Your normal website content that exists in the content section.
Media content such as images, videos and PDFs that are stored in the Media section.
Finally Members, used for user profiles and frontend authentication which you can find in the Members section.
A fundamental principle in Umbraco is that all content types have a definition (Document Types, Media Types, Member Types). These definitions are highly customizable, meaning you can add properties and have complete control over how the data is organized.
Defining Documents Types, adding properties and creating content.
Defining Media Types and uploading files to the media section, using upload fields and image cropper.
Defining Member Types and creating members for authentication and user profiles.
Creating and editing Data Types.
Schedule when content should be published / unpublished automatically.
Overview of how to add and reorder tabs, convert a group to a tab and manage the “Generic” tab
Control who has access to the Umbraco backoffice and what permissions they have.
An introduction to Relations and Relation Types, creating, and managing relationships between different entities in Umbraco.
Using Dictionary Items, you can store a value for each language. Dictionary Items have a unique key which is used to fetch the value of the Dictionary Item.
How to keep the noise down whilst ensuring your important content versions stick around indefinitely.
Here you will learn how to apply localization for Document Types in Umbraco.
The Umbraco backoffice is fully localized to match the user's configured language. When defining Document Types, you can apply localization to:
Document Type names and descriptions.
Property names and descriptions.
Custom property validation messages.
Tab and group names.
Setting up localization for Document Types is a two-step process:
Create the localizations in user defined language files.
Apply the localizations to the Document Types.
Everything in this article also applies to defining Media Types.
User defined language files are created in /config/lang and must be named {language}.user.xml. For example: en-us.user.xml.
There are no specific requirements as to how localizations should be structured for use in Document Types. The following localizations have been used for the samples in this article:
Umbraco must be restarted to pick up on changes to language files.
The localizations are applied by using the syntax #{area alias}_{key alias}.
Create a Document Type with template called #contentTypes_article with alias: articlePage.
Under the newly created Document Type follow these steps:
Name the description to #contentTypes_article-desc.
Create a new tab called #tabs_content.
Add a new group called #groups_titles.
Add a property called #properties_title with alias title.
Set description to #properties_title-desc.
Use a TextString editor.
Enable to Set this field as mandatory.
Under validation add #properties_title-message.
Add a property called #properties_subTitle with alias subTitle.
Set description to #properties_subTitle-desc.
Use a TextString editor.
Enable to Allow as root in the Permissions tab.
When creating and editing the content, you will see that the backoffice now uses the configured localizations.
Create a new "Article" content:
When trying to save the content without adding the mandatory content, you will see a warning as expected:
Here you'll find an explanation of how content is defined in Umbraco
Before a piece of content can be created in the Umbraco backoffice, first it needs to be defined. That is why, when opening a blank installation of Umbraco, it is not possible to create content in the Content section.
All content needs a blueprint that holds information about what kind of data can be stored on the content node or which editors are used.
Additionally, it also needs information on how it is organized, where in the structure it is allowed, and so forth. This blueprint or definition is called a Document Type.
Document Types define what kind of content can be created in the Content section and what an end-user sees and can interact with.
It can define entire pages or more limited content that can be reused on other nodes ie. a Search Engine Optimization (SEO) group. This means that you are in complete control of what type of content can be created and where.
Another example is if there is a "Blog post" Document Type that has some properties containing a thumbnail, a name, and an author image. Then all blog posts using the "Blog post" Document Type, will allow the end user to fill in a thumbnail, author name, and an author image.
A Document Type contains fieldsets (or groups) where you can apply rules about where the content can be created, allowed template(s), backoffice icons, etc.
A Document Type is created using the Document Type editor in the Settings section.
Go to the Settings section in the backoffice.
On the Document Types node click the menu icon (•••) to bring up the context menu.
Here choose Document Type with Template. This will create a new Document Type with a template. The Template can be found under Templates in the Settings section which will be assigned as the default template for the Document Type.
First, we're prompted to give the Document Type a name. This first Document Type will be the root node for our content, name it "Home".
The alias of the Document Type is automatically generated based on the property name. If you want to change the auto-generated alias, click the "lock" icon. The alias must be in camel case. For example: homePage.
Having a root node lets you quickly query content as you know everything will be under the root node.
Choosing appropriate icons for your content nodes is a good way to give editors a better overview of the content tree.
To set an icon for the Document Type click the document icon in the top left corner. This will open the icon select dialog. Search for "Home"and select the icon. This icon will be used in the content tree.
This will allow this Document Type to be created as the first content in the Content section.
Go to the Permissions tab
Tick the Allow as root toggle
Save the Document Type by clicking save in the bottom right corner.
Now that we have the Document Type in place, we can create the content.
Go to the Content section
Click on the menu icon next to Content
Select the "Home" Document Type. We'll name it "Home"
Then click the Save and Publish button.
As we haven't created our properties, all we can see on the "Home" node is the Properties tab. This tab contains the default properties that are available on all content nodes in Umbraco.
Let's add some properties of our own.
In order to add the option to create different content on the same Document Type, some groups and properties need to be added.
Groups
Groups are a way to organize and structure the properties within the content, making it more manageable. It also makes it more user-friendly for content editors when creating or editing content on a website.
A name can be added to the group and after properties can be added.
Properties
Each field on a Document Type is called a property. The property is given a name, an alias (used to output the properties contained in a template), and an editor.
Some editors require configuration where a configured editor is saved as a Data Type and can be reused for multiple properties and document types. These can be seen in the Settings section under Data Types.
Go to the Settings section
Expand Document Types by clicking the arrow to the left
Select the "Home" Document Type.
Keyboard Shortcuts
Keyboard shortcuts are available when you are working with the Document Type editor. To see which shortcuts are available, click ALT + SHIFT + K.
Before we start adding properties to the Document Type we need to create a group to hold the property.
Click Add group and name the group "Content".
If you have multiple groups and/or properties you can order them with drag and drop or by entering a numeric sort order value. This is done by clicking Reorder.
Now that we have created a group we can start adding properties. Let's add a Rich Text editor to the Content group.
Click the Add property link in the Content group. This opens the property settings dialog. Here you can set the metadata for each property (name, alias, description)
Choose which Data Type/property editor to use, and add validation if needed.
Give the property a name. The name will be shown to the editor to make it relevant and understandable. Notice the alias is automatically generated based on the name. We'll name this "Body Text".
Clicking Select editor will open the Select editor dialog. Here, you can choose between all the available editors on the Create a new configuration tab. This will create a new configuration or already configured editors in the Available configurations tab.
To make it easier to find what you need use the search field to filter by typing "Rich". Filtering will display configured properties first (under Available configurations) and all available editors under that.
Select the Rich Text editor under Create new. This will let you configure the editor settings - the Rich Text editor for this property.
The name of the Data Type is based on the name of the Document Type, the name of the property, and the property editor. Flor example: Home - Body Text - Rich Text editor.
Let's rename it to "Basic Rich Text editor" and only select the most necessary options.
bold
italic
alignLeft
alignCenter
link
umbMediaPicker
When you are happy with the settings click Submit.
Selecting the Mandatory toggle makes the property mandatory and the content cannot be saved if no value is entered (in this case, the Richtext editor).
You have the option to add additional validation by selecting a predefined validation method under the Custom validation dropdown (such as email, number, or URL). Or by selecting a custom validation and adding a regular expression.
Save the Document Type.
If you go to the Content section and click on the Home node you will now see the Contentgroup with the Body Text property.
The description of the property is not necessary, but it´s a best practice as it guides the editor to use the property correctly. The property description supports some markdown and one custom collapse syntax:
Now if we put it all together we get something like this:
Next up we'll create a text page Document Type that will be used for subpages on the site.
Go back to the Settings section
Create a new Document Type
Name it "Text Page".
Add a group called "Content"
This time we'll add two properties:
First, make a property called "Summary" using the Textarea editor
Secondly, create a property called "Body Text" and reuse the Rich Text Editor Data Type.
Before creating a Text Page in Content section, allow the Text Page Document Type to be created as a child node to the Home node.
Select the "Home" Document Type
Go to the Permissions group.
Click Add child
Select "Text Page".
Go to the Content section
Click the menu icon (•••) next to the "Home" node
Select the "Text page" Document Type. We'll name the page "About us".
We now have a basic content structure.
Document Types are flexible and can be used for defining pieces of reusable content or an entire page, to act as a container or repository.
You can also export document types from an already existing project/installation and import them into another project/installation.
Go to the Settings section
Right-click the Document type
Select Export. When you click on the Export button, the Document Type is saved as a *.udt file.
To import a Document Type:
Go to the Settings section
Right-click the Document type
Select Import Document Type
Click on the Import button and browse to the Document Type you exported. The Name and Alias of the Document Type are displayed.
Click Import to complete the process.
If your Document Type contains compositions or inherits from another Document Type, then you need to export/import the Composition/Document Type too.
You cannot export/import document types on Umbraco Cloud.
Members are used for registering and authentication external / frontend users of an Umbraco installation. This could be Forum members and Intranet members.
Members are used for registering and authenticating external users of an Umbraco installation (ie. forum members, intranet users and so forth).
This guide will explain how to define and create members in the backoffice. If you want to work with members using the service APIs, links can be found at the end of the document.
There is a default Member Type that can be used to create members. You can customize this to fit your needs or create your own Member Type from scratch.
Go to the Members section, right-click Members in the member tree, click Create and choose Member.
Members have a number of mandatory properties that need to be filled in before a member can be saved. The properties are Login, Email, and the two Password fields in the Member tab.
There are also a number of default properties in the Member tab which are stored in the database in the tables Member andTwoFactorLogin:
umbracoMemberFailedPasswordAttempts
umbracoMemberApproved
umbracoMemberLockedOut
umbracoTwoFactorLogin
umbracoMemberLastLockoutDate
umbracoMemberLastLogin
umbracoMemberLastPasswordChangeDate
Once the Member is created and saved you can access it by expanding the Members tree and clicking All Members to get a list view. You can also view members of a specific type by selecting the member type in the Members tree.
Sensitive properties on a members data will not be displayed to backoffice users unless they have appropriate permissions. In order to see the values of the default properties in the Member tab you need to have the Sensitive data User Group. By having this group added to a user they will also have the option to mark member type properties as sensitive.
You can create your own Member Types and add tabs, groups and properties as you would with Document Types.
Go to the Settings section, right-click Member Types and select Create. You will now be taken to the Member Type editor that is used to define and edit the Member Type. Name the new Member Type and click Save.
Once created, the Member Type will have no properties, so you have the freedom to add your own properties or compositions.
When creating a Member Type you can assign compositions. Compositions allow you to inherit tabs and properties from existing member types instead of creating them from scratch.
For example on the member type that you have created, click on Composition. Then you can choose the existing Member type which then you will inherit its tabs, groups, and properties.
The default Member type has a Membership group which includes umbracoMemberComments property along with the other default properties. The other properties can be seen only in the Member tab when creating a member.
It is possible to add more groups and more properties to each of the Member Types you create, as well as the default Member Type.
Member Groups define roles for your members that can be used for role-based protection. A member can be in multiple groups.
To create a new Member Group click the menu icon next to the Member Groups node in the Members section. Choose Create, name the group, and save the group.
To assign a member to a specific group find the member you wish to assign and find the Properties group. Here you can see which groups the member is already part of. You can also add the member to more groups or remove the member from already assigned groups:
As a developer you are able to leverage your website when you build on the Members section of Umbraco. The member's section is by default in the Umbraco backoffice, but you can still use it to implement some work on your front end. Members are created using ASP.NET Core Identity, so there are some provider settings that can be set in appsettings.json - here are the defaults:
You can find out more about the services methods in the reference section of the documentation by following the links below.
Learn how to work with different types of Media content on your Umbraco website.
Media in Umbraco CMS is handled the same way as content. You define Media Types that act as a base for media items. The following default Media Types are available:
Article - used for uploading and storing documents.
Audio - used for uploading and storing digital audio files.
File - used for uploading and storing different types of files in the Media section.
Folder - a container for organizing media items in the Media section tree.
Image - used for uploading and storing images.
Vector Graphics (SVG) - used for uploading and storing Scalable Vector Graphics (SVG) files which are text files containing source code to draw the desired image.
Video - used for uploading and storing video files.
The default Media Types aim to cover most needs for media on a website. You do not need to define your Media Types to start using the Media section. The tools for organizing and uploading the media are already in place.
If you have upgraded from an older version than 8.14 the Media Types listed above are not added automatically. You can add those types manually yourselves by following the steps below . On the , you will find a detailed overview of all Media Types.
You can upload media in two different ways:
and
From the Media section in the Umbraco backoffice, you can add new media items by following either of the approaches defined below:
Use the Create dialog to create a new Media item in the Media section
The Media item will be created based on the type you choose.
Upload the image or file, give the Media item a name, and click Save.
Use the Drag and drop feature to add your files to the Media section.
Umbraco will automatically detect the Media Type and create the Media item.
You can drop entire folder structures to recreate that same structure in the Media section.
New media items can be added to your site without interrupting the content creation flow. This can be done following either of the two approaches outlined below.
Drag and drop the image(s) from your file explorer directly into the Media Picker property on the Content page.
Images added this way is automatically added to the user's start node in the Media section of the Umbraco backoffice.
Select the "+" icon to open the "Select media" dialog where you can add images from your file explorer directly or using drag and drop.
It is always a good idea to start by creating a folder for your media items. It can be a good idea to align these folders with the content on your website. This will give the editors a better overview of the files and enable them to upload media items in the correct place.
Follow these steps to create a folder in the Media section:
Go to the Media section.
Select ... next to Media.
Alternatively, you can right-click the Media node and select Create.
Select Folder.
Enter a name for the folder and select Save in the bottom-right corner.
The Image Media Type has 5 properties: Upload Image, Width, Height, Size, and Type. These are populated once the image is uploaded. The properties can be viewed in the Media section and accessed in your Templates.
Except for the Folder Media Type, the other Media Types have 3 properties: Upload Image, Type, and Size.
The default view for the Media section is a card view that lets you preview the different files that have been uploaded.
By selecting multiple media items it is possible to perform bulk operations like moving or deleting the items.
To edit properties on a single media item, click the name of the item, which you will see once you hover over the item.
From the top-right corner of the Media section, you can toggle between list and grid view. There is also an option to search for the items in the Media section.
You can switch to a list view by selecting the view toggle next to the search field and selecting the list view.
By adding a Media Picker property to a Document Type the editor will have the ability to select media items when creating content.
You can create custom Media Types and control the structure of the Media tree as you would with Document Types. This means you can store information that is specific to the media on the item itself.
A Media Type is created in the Settings section using the Media Type editor.
Go to the Settings section.
Click ... next to Media Types (or right-click the Media Types node).
Choose New Media Type.
Name the new Media Type Employee Image.
Choose an icon by selecting the icon left of the name field.
You will now see the Media Type editor. It is similar to the editor used for creating Document Types.
Having different folders for different Media Types makes it possible to restrict where media items can be created and added. Only allowing PDF uploads in a certain folder and employee images in another make it easier to keep the Media section organized.
Before we start adding properties to the Media Type we need to add a group to put these in.
Click on Add group.
Call the group Image.
We need to add the same properties as on the default Image Media Type. These are:
umbracoFile
umbracoWidth
umbracoHeight
umbracoBytes
umbracoExtension
Follow the steps outlined below to add the properties to the Media Type:
Click Add property.
Name it Upload image.
Change the alias to umbracoFile.
Click Add editor.
Search for cropper and choose Image cropper under Create new.
Rename the editor Employee Image Cropper.
Add two new crops called Thumbnail (200px x 350px) and wideThumbnail (350px x 200px).
Name the remaining four properties Width, Height, Size, and Type, and give them the aliases as mentioned above. They should all use the Label editor.
As mentioned before these properties will automatically be populated once an image has been uploaded.
Next up, we will create a folder to hold the employee images. We could use the existing Folder Media Type but that would mean editors can upload employee images to any folder of that type. If we create a folder specifically for employee images there is only one place to put them.
Go back to the Settings section and create a new Media Type.
Name it Employee Images.
Select the folder icon by clicking the icon to the left of the name.
Navigate to the List view tab.
Toggle the Enable list view option.
The new folder should be allowed to be created in the root of the Media tree. We also need to allow only the Employee Image Media Type in our new folder. Both of these configurations can be set on the Permissions tab.
Go to the Permissions tab.
Toggle the Allow as root.
Click Add child under Employee Images.
Select Employee Image.
Go to the Media section.
Select ... next to Media and select the Employee images folder.
Name it Employee Images and select Save.
There are four options to add new media items to the folder, as you can see here:
Uncheck the Allow at root option on the Employee Images Media Type to prevent the creation of multiple folders of this type. This will only disable the creation of new ones and not affect existing folders.
If you select an image that has been uploaded to the folder you will see the full image and the two defined crops.
Moving the focal point circle on the image will update the crops to focus accordingly. You can also edit the individual crops by selecting them and moving the image or adjusting the slider to zoom.
You can also choose to create a Document Type without a template and create Folders to organize your Document Types. Other options are to create Compositions and Element types, which you can read more about in the section.
The editor determines what type of data the property will store and the input method. There is a wide range of default available and you can .
To convert a group to a tab, see the section in the article.
More information can be found under .
Video:
Video:
Video:
Learn more about each Media Type in .
A new version is created whenever you save and publish a content item in Umbraco. This is how you can roll back to a previous version. Every saved version stores a record in the database, not only for the version but also for each content item property for that version. In a multi-lingual site, further rows are added for every culture variation. Over time this amount of data can build and swallow up the capacity of your SQL Server and slow the performance of the Umbraco backoffice.
The default cleanup policy will:
Not delete any versions created over the previous 4 days. The recent version history is preserved. See the KeepAllVersionsNewerThanDays setting.
'Prune' versions 4 days after they are created. The last version of a content item saved on a particular day will be kept but earlier versions from that day will be deleted.
Delete all versions older than 90 days. See the KeepLatestVersionPerDayForDays setting.
Never delete any versions that are currently 'published'.
Never delete any specific versions marked as 'Prevent Cleanup' in the Backoffice version history.
Based on the default cleanup policy, you can roll back content to the latest version saved on a particular day as long as it was
Created within the last 90 days, or
Marked as "Prevent Cleanup" in the Backoffice version history.
The History section, which acts as an audit log, is not cleared out, and will continue to show logs for versions older than 90 days.
The feature can be configured in the appSettings.json:
For sites with stricter requirements, it is possible to opt-out of both options globally, see ContentSettings and by Document Type.
Additionally, it is possible to keep the feature enabled but mark specific versions to keep forever.
It is worth noting that whilst we delete rows, we do not shrink database files or rebuild indexes. For upgraded sites with a lot of history you may wish to perform these tasks. If they are not part of your regular database maintenance plan already.
It is possible to override the global settings per Document Type in the backoffice to prevent unwanted cleanup. This can be managed in the "permissions" Content App for each Document Type.
It is possible to mark important content versions as "prevent cleanup" to ensure they are never removed. This happens via the new and improved rollback modal which can be found on the "info" content app for each document.
Open rollback modal.
Click Prevent cleanup button for each important version.
This guide will explain how to define, create, and manage users in the backoffice
Users (not to be confused with Members) are people who have access to the Umbraco backoffice. These could include Content Editors, Translators, Web Designers, and Developers.
This guide will explain how to define, create, and manage users in the backoffice.
Go to the Users section. Here, you will see an overview of all the current backoffice users.
To create a new user select the Invite user button. You will be prompted to add a Name and an Email for the new user. You will also need to select which User group the new user should be added to and enter a Message for the invitation.
Once you have created the user, an autogenerated password will be provided. This password needs to be used to access the account.
There are default properties on every user that can be defined:
Change/Remove photo.
Change Password (provides option to set a new password).
Disable (allows one to disable service access).
Update the email for the user.
Language (sets the backoffice language of the user account).
User Group (determines scope of access in the backoffice)
Start nodes for both Content and Media sections to limit the access
By default, the User Groups available to new users are Administrators, Writers, Editors, Translators and Sensitive Data.
Administrator: Can do anything when editing nodes in the content section (has all permissions).
Editor: Allowed to create and publish content items or nodes on the website without approval from others or restrictions (has permissions to Public Access, Rollback, Browse Node, Create Content Template, Delete, Create, Publish, Unpublish, Update, Copy, Move and Sort).
Writer: Allowed to browse nodes, create nodes, and request for publication of items. Not allowed to publish directly without someone elses approval like an Editor (has permissions to Browse Node, Create, Send to Publish and Update).
Translator: Are used for translating your website. Translators are allowed to browse and update nodes as well as grant dashboard access. Translations of site pages must be reviewed by others before publication (has permissions to Browse Node and Update).
Sensitive data: Any users added to this User group will have access to view any data marked as sensitive. Learn more about this feature in the Sensitive Data article.
You can also create your own custom User Groups and add properties and tabs as you would with Document Types and Member Types.
Go to the Users section and select the Groups tab in the top-right corner.
Select Create group and you will be taken to the User Group editor. Here you can define and edit the User Group through custom settings and properties.
Shows basic information about the User Group and settings for custom properties.
Name: The name of the User Group shown in the User Group tab.
Alias: Used to reference the User Group in code - the alias will be auto-generated based on the name.
Assign access: Define which sections and languages the users will have access to, and if the users should have access to only some or all content and media.
Default Permissions: Selects the default permissions granted to users of the User Group.
Granular permissions: Define a specific node the users in the group should have access to.
Users: Add users to the new group.
Depending on which User Group a user is added to, each user has a set of permissions associated with their accounts. These permissions either enable or disable a users ability to perform its associated function.
The available user permissions are defined under Default Permissions in the User group.
When a new user is created, you can set specific permissions for that user on different domains and subdomains. You can also set permissions on different User Groups, even for the default types.
As a developer you are only able to leverage your website from the backoffice when you build on the Users section of Umbraco. This is because the Users section is restricted to the Umbraco backoffice.
Umbraco Forms has a backoffice security model integrated with Umbraco Users. You can manage the details in the Users section of the backoffice, within a tree named Forms Security.
On this page you will find the media types and Data Types in Umbraco. These types are not created automatically after an upgrade. If you want to use the new types, you can create them yourself.
The UploadArticle Data Type has the following configuration:
Property editor: FileUpload
Accepted file extensions: pdf, docx, doc
The UploadAudio Data Type has the following configuration:
Property editor: FileUpload
Accepted file extensions: mp3, weba, oga, opus
The UploadVectorGraphics Data Type has the following configuration:
Property editor: FileUpload
Accepted file extensions: svg
The UploadVideo Data Type has the following configuration:
Property editor: FileUpload
Accepted file extensions: mp4, webm, ogv
The UmbracoMediaArticle media type has the following properties:
umbracoFile - Upload File
umbracoExtension - Label (string)
umbracoBytes - Label (bigint)
The UmbracoMediaAudio media type has the following properties:
umbracoFile Upload Audio
umbracoExtension Label (string)
umbracoBytes Label (bigint)
The UmbracoMediaVectorGraphics media type has the following properties:
umbracoFile - Upload Vector Graphics
umbracoExtension Label (string)
umbracoBytes Label (bigint)
The UmbracoMediaVideo media type has the following properties:
umbracoFile - Upload Video
umbracoExtension - Label (string)
umbracoBytes - Label (bigint)
You can also create localization files for Media Types. You can read more about this in the Document Type Localization article.
On this page, you will find the default Document Types in Umbraco. If you want to use these document types, you can create them in the Settings section.
Creating document types with templates allows you to define both the content structure and the visual presentation of a particular type of content item. It ensures a consistent and cohesive look and feel across your website while also enabling structured content management. This approach helps separate content from design, making it easier to manage and update your website's content and appearance independently through templates.
Creating a Document Type (without a template) is about defining the content structure and fields that can be used across different content items. You might use document types without templates for creating consistent, structured content that doesn't require a predefined page layout. For example blog posts or product listings.
Compositions provide a way to create reusable sets of properties that can be added to one or more document types. This can help simplify the management and consistency of content types across your website.
When using a mixed setup, you can take advantage of nesting and use compositions by clicking on "Compositions..." option.
If you create 2 compositions that contain some common properties it is only possible to pick one of the compositions in a Document Type. If preferred, those compositions that cannot be used can be marked as hidden by checkmarking the Hide unavailable options.
An Element Type is a Document Type without a template containing schema configurations for repeating a set of properties. These are for defining schema in the Block List Editor, Block Grid Editor, or other Element Type based editors.
Element Types cannot be used to create content that resides in the Content tree. When you create an Element type, it automatically sets the Is Element Type flag to True on the Permissions tab.
Element Types are created using the same workflow as regular Document Types but usually contain fewer properties. You can also create Element Types as part of configuring a Block Grid or Block List Data Type.
Learn about the data types in Umbraco.
A Data Type defines the type of input for a property. So when adding a property (on Document Types, Media Types and Members) and selecting the Type you are selecting a Data Type. There are preconfigured Data Types available in Umbraco and more can be added in the Settings section.
A Data Type can be something basic (textstring, number, true/false,...) or it can be more complex (multi node tree picker, image cropper, Grid Layout).
The Data Type references a Property Editor and if the Property Editor has settings these are configured on the Data Type. This means you can have multiple Data Types referencing the same Property Editor.
An example of this could be to have two dropdown Data Types both referencing the same dropdown Property Editor. One configured to show a list of cities, the other a list of countries.
To create a new Data Type, go to the Settings section within the backoffice. Thereafter click the menu icon to the right of the Data Types folder and select Create->New Data Type. Name the Data Type - we'll call it Dropdown Cities.
Property Editor: This is where you pick the Property Editor that our Dropdown Cities Data Type will be referencing. Pick the Dropdown and now you will see the configuration options that are available for a Data Type referencing the Dropdown Property Editor.
Enable multiple choice: By enabling this it will be possible to select multiple options from the dropdown.
Add prevalue: Here you can add prevalues to the Data Type by entering the value you want into the input field and pressing the add button or hitting Enter on your keyboard.
When you're happy with the list press Save. It is now possible to select this Data Type for a property on Document Types, Media Types, and Members. Doing this will then create a dropdown list for the editor to choose from and save the choice as a string.
To customize an existing Data Type go to the Settings section, expand the Data Types folder and select the Data Type you want to edit.
Besides the Data Types that are available out of the box there are some additional Property Editors. For example, think of the Slider and Block List.
To view the Data Type reference, go to the Settings section and expand the Data Types folder. Select the Data Type you wish to view the reference for and click the Info tab.
This gives you an overview of the Types that currently use the Data Type.
Learn more about viewing references or implementing tracking in the Tracking References article.
What are relations, how to create and manage them
Umbraco sections are built around the concept of 'trees' and there is an implicit relationship between items in a section tree.
We refer to these relationships in the manner of a 'Family Tree' - eg, One content item might be the 'Parent' of some content items, and those content items would be referred to as the 'Children' of that parent. Items within the same branch of the tree can also be described as 'Ancestors' or 'Descendants' of an item, depending if they are above or below them in the depth of the tree.
There are methods in Umbraco to support querying content items by their relative position in the tree to the current page using these concepts, eg Model.Ancestors() or Model.Children() or Model.Descendants() - but what about 'Cousins'?
What if there are no direct Parent/Child/Ancestor/Descendant relationships between two items in a tree, but they are still somehow 'related' in the context of your website? For example, the alternate language translation pages of a content page.
What if there is also a 'relation' between different types of Umbraco entities in your site, eg Content -> Member or Member -> MediaFolder? Perhaps, you'd like to be able to retrieve and display the uploaded images from a specific logged-in Member.
These are the scenarios where the concept of Umbraco Relations provides a solution.
Umbraco Relations allow you to relate almost any object in Umbraco to almost any other Umbraco object - under a defined Relation Type.
With a Content/Member/Media picker that you might add to a Content Type - the relationship is ONLY 1-way. Your content item knows it has 'picked' another content item, perhaps to display a shared banner across different pages, but that 'banner' content item doesn't know where it has been picked!
Umbraco Relations are 2-way, when you create a relation between two different types of entities, you can alway find one entity from the other and vice versa. eg you could list out in the backoffice all the pages that a content banner had been picked on.
To create and use Relations in your Umbraco Website, you need to define a 'Relation Type' to specify what the two types of entities will be relatable and to give the Relation Type an alias. So, you can test if two items are related for a particular 'relation type'. Two items might be related under multiple different Relation Types, and you might be only interested in your 'Related Language Page' Relation Type.
Navigate to the Settings section in the Umbraco backoffice and you'll find the Relation Types folder in the Settings tree.
If you expand the Relation Type tree, you can see that Umbraco 'ships' with some default Relation Types. These are used by the Umbraco backoffice to help deliver some key backoffice functionality:
For example, there is a Relation Type that tracks when Media is picked in Content to be able to provide the functionality of warning an editor if they try to delete a Media Item that it is 'in use'. There is a Relation Type, to help 'restore' deleted content back to the place it was deleted from in the Recycle Bin.
To create your new Relation Type, follow these steps:
Right-click the Relation Types folder.
Provide a Name for the Relation Type. This will generate it's alias.
Choose the Direction of the relationship, for example, usually Bidirectional to get the benefits of relations.
Define the type of one object in the relation called Parent that defines which column in the database this value is stored in.
For a bidirectional relationship, it doesn't matter which type of entity is defined as the Parent or the Child. If there is 'one thing' that will be related to lots of 'other things', then choose that thing as the Parent.
Choose the different types for each entity (Parent and child) from the drop-down list.
Currently the available types are: Document(Content), Media, Member, Document Type, Media Type, Member Type, Member Group, Data Type, Root, and Recycle Bin
Example: For relating Members to their uploaded Images, we might create a 'Member Images' relation
Select Is Dependency as Yes if you wish this Relation Type to be used in Umbraco's 'tracking' functionality; that warns editors when trying to delete entities if they are 'used' in a Relation Type marked as 'Is Dependency'
Click Create and you'll see your new Relation Type created in the Relation Types folder. You can see the 'Alias' that you'll need to make note of when working with Relations.
To view one of the existing Relation Types, go to the Relations tab. It displays a long list of all the objects that have been related for this specific Relation Type.
You can create Relations using the RelationService API via code.
Some examples are provided here in the RelationService Documentation Page
You might want to create a 'Relation' between two objects either as:
A response to a backoffice event. For example, a content item being published that has picked several other content items. Storing a relationship between these items would make querying between them easier. Perhaps show all the pages on which a particular 'banner' has been picked.
A logged-in member on the front end of an Umbraco website might have the facility to upload images. In response, the implementation could store the photos programmatically in the Media Section and at the same time, create a Relation to record the relationship between the member and their uploaded pictures. On an image gallery page, it would be possible to display all the gallery images for the current logged-in Member using the relations.
Some of the community packages that use Relations are listed below:
'Relations Picker' - a content picker that automatically creates Relations.
'ContentRelations' - allows you to relate two items via the Backoffice.
'LinkedPages' - Provides a LinkedPages context item to show, edit, and add relations between content pages.
In this section, an overview is given of how to add and reorder tabs, convert a group to a tab and manage the “Generic” tab.
Using tabs, you can organize properties in the backoffice to provide a tailored and efficient workflow for editors creating and maintaining Content, Media and Members.
Tabs allow you to add horizontal organization in your Document Types, Media Types and Member Types. This is handy for types that need a more defined hierarchy or have many properties and groups.
To add a tab, follow these steps:
Go to Settings.
Create or select a Document Type/Media Type/Member Type and click Add tab.
When adding the first tab, all existing groups are automatically added to the tab.
To reorder tabs, follow these steps:
Go to Settings.
Select a Document Type/Media Type/Member Type.
Select Reorder.
You can drag the tab where you want, manually add a numeric value next to the tab name or use the arrows to set a value.
This is important when using compositions, as you want to always display a tab/group at a certain position by setting a manual numeric value.
Select I am done reordering.
Click Save.
To convert a group to a tab, follow these steps:
Go to Settings.
Select a Document Type/Media Type/Member Type.
Select Reorder.
You can drag the group to the Convert to tab option.
Select I am done reordering.
Click Save.
Converting a tab back into a group is not possible, as tabs can contain groups, and nested groups are unsupported. To overcome this, create a new group and transfer all tab properties into it, then delete the empty tab.
Once you start adding tabs, you might see a “Generic” tab appear. This is done to hold groups and properties that are not assigned to a tab. For example, a group of properties coming from a composition that has no tab. In order to display the groups and properties correctly and have a solid data structure, they will be displayed under the “Generic” tab.
To manage the Generic tab on a Document Type/Media Type:
Go to the Composition Document Type/Media Type.
Click Add tab and enter the Name for the tab. All existing groups and properties are added to the tab.
Go to the Document Type/Media Type, the Generic tab will now be replaced by the tab from the composition.
Each document in Umbraco can be scheduled for publishing and unpublishing on a pre-defined date and time.
Each document in Umbraco can be scheduled for publishing and unpublishing on a pre-defined date and time.
You can find the options to do this click on the arrow next to the Save and publish button and pick Schedule...
This will open a Schedule Publishing dialog where you can specify dates and time.
Your server may be in a different timezone than where you are located. You are able to select a date and time in your timezone and Umbraco will make sure that the item gets published at that time. So, if you select 12PM then the item will be published at 12PM in the timezone you are in. This may be 8PM on the server, which is indicated when you select the date and time.
If you are in the same timezone as the server, this message will not appear under the date picker.
In Umbraco versions lower than 7.5, the time you select has to be the time on the server. These older versions of Umbraco do not detect your local timezone.
All users with access to the Content section in the Umbraco backoffice are able to schedule content for publish/unpublish.
In some cases you will need to adjust your configuration to ensure that scheduled publishing/unpublishing works. The schedule works by the server sending an HTTP(S) request to itself.
If you are in a load balanced environment special care must be given to ensure you've configured this correctly, see the docs here
If you are not load balancing, the way that Umbraco determines the base URL to send the scheduled HTTP(S) request to is as follows:
umbracoSettings:settings/web.routing/@umbracoApplicationUrl if it exists (see these docs for details)
Else umbracoSettings:settings/scheduledTasks/@baseUrl if it exits (deprecated)
Else umbracoSettings:distributedCall/servers if we have the server in there (deprecated, see load balance docs)
Else it's based on the first request that the website receives and uses the base URL of this request (default)
If the umbracoApplicationUrl is used, the value also specifies the scheme (either HTTP or HTTPS). The request for scheduled publishing will always be sent over HTTPS if the appSettings umbracoUseSSL is set to true.
If your scheduled publishing/unpublishing is not working as expected it is probably an issue that your server cannot communicate with the scheduled publishing endpoint. This can be caused by a number of reasons such as:
Url rewrites in place that prevent the endpoint from being reached
DNS misconfiguration not allowing the server to communicate to the base URL used in the first request that the website receives - which could be directly affected by a firewall/Network Address Translation (NAT)/load balancer that your server sites behind
Secure Sockets Layer (SSL) and/or umbracoUseSSL misconfiguration not allowing the server to communicate to the scheduled publishing endpoint on the correct http/https scheme
To better diagnose the issue you can temporarily change your log4net config settings to be DEBUG instead of INFO. This will give you all sorts of information including being able to see whether or not the scheduled publishing endpoint is being reached or not.
In some cases it might be easiest to specify the umbracoSettings:settings/web.routing/@umbracoApplicationUrl setting. This is to ensure that your server is communicating to itself on the correct URL.
Creating Dictionary Items in Umbraco
Depending on how your site is set up, not all content is edited through the Content section. There might be some text in your templates or macros that needs translation. Using Dictionary Items, you can store a value for each language. Dictionary Items have a unique key that is used to fetch the value of the Dictionary Item.
Dictionary Items can be managed from the Translation section. Let's take a look at an example. In this example, we will translate "Welcome to Umbraco" from within the template and add it to the dictionary:
To add a Dictionary Item:
Go to the Translation section.
Click on Dictionary in the Translation tree and select Create.
Enter the Name for the dictionary item. Let's say Welcome.
Click Create.
Enter the values for the different language versions.
Click Save.
To group dictionary items:
Go to the Translation section.
Click on Dictionary in the Translation tree and select Create.
Enter the Name for the dictionary item. Let's say Contact.
Click Create.
Click on Contact and select Create.
Enter the Name of the item to be created under the Contact group.
Click Create.
Enter the values for the different language versions.
Click Save.
To edit a dictionary item, follow these steps:
Go to the Translation section.
Use the Dictionary tree to locate the item you need to update/edit.
Alternatively, you can use the search field in the top-right corner.
Make the edits you need to make.
Click Save to save the changes.
It will only be possible to edit the language(s) that the given user has access to. The value of the remaining languages will be read-only.
Which language a user has access to is determined by the "Language permissions" set on the User Group. Learn more about this feature in the Users article.
In some cases, you might want to render the dictionary values in the Document Type. This is to display the labels depending on the language configured for the logged-in user.
To use dictionary values in the Document Type, follow these steps:
Go to the Settings section.
Open the Document Type where you want to use the Dictionary value.
Locate the label and type #MyDictionaryKey. For example: #Welcome or #WelcomeDescription.
Click Save.
Go to the Content section.
View the content node using the Welcome property. The property will display the dictionary value per the user's configured backoffice language.
You can translate tabs and property groups in the backoffice as well. For more information, see How to Translate Umbraco Backoffice Document Types video.
To fetch dictionary values in the template, replace the text with the following snippet:
Alternatively, you can specify an altText which will be returned if the dictionary value is empty.
In some cases, you might want to use the same Dictionary Items on multiple Umbraco websites. For this, you can use the export and import functionality to quickly copy the items from one website to another.
Go to the Translation section in the Umbraco backoffice.
Locate the Dictionary Item (or group) you want to copy in the section tree.
Right-click the item.
Select Export....
Decide whether you want to also include descendants.
Click Export.
This will download a .udt file which you can use to import the Dictionary items on another Umbraco website.
Go to the **Translation section in the Umbraco backoffice.
Right-click on the top of the Dictionary tree.
Select Import....
Click on Import.
Find and select the .udt file containing the Dictionary Items.
Click Open in the file browser.
Review the Dictionary Items for import.
Choose where to import the items.
Click on Import.
The Dictionary Items have now been added to your website.
To use Dictionary Items in a multilingual website, see the Creating a Multilingual Site article.
Learn about the default data types in Umbraco.
Here's a list of the default Data Types that come installed with Umbraco. There are plenty more that you can create based on the installed Property Editors.
Adds a list of approved colors. The approved colors are added as hex values by using the color picker. Optionally, you can enable labels to give the colors different names.
Displays a list of preset values as a list of checkbox controls. The preset values are modified in the Settings section under Data Types in Checkbox List where new items can be added. The value saved is a comma-separated string of prevalue IDs.
The Content Picker opens a modal to pick a specific page from the content structure. The value saved is the selected page's ID.
Displays a calendar UI for selecting date and time. The value saved is a standard DateTime value but does not contain time information.
Displays a calendar UI for selecting date and time. The value saved is a standard DateTime value.
Displays a list of preset values as a list where only a single value can be selected. The default Data Type does not contain any prevalues. The value saved is the selected value as a string.
Displays a list of preset values as a list where multiple values can be selected. The default Data Type does not contain any prevlaues. The value saved is a comma separated string of prevalue IDs.
Allows to upload and crop images by using a focal point. Specific crop definitions can also be added. This Data Type is used by default on the Image Media Type.
The Image Media Picker opens a modal to pick images from the Media tree or images from your Computer. The value saved is the selected media node UDI.
Is a non-editable control and can be used to only display the value. It can also be used in the Media section to load in values related to the node, such as width, height and file size.
There are six Label Data Types:
Label (bigint) - Allows to save a big integer value for a Label.
Label (datetime) - Allows to set a DateTime value for a Label.
Label (decimal) - Allows to set a decimal value for a Label.
Label (integer) - Allows to set an integer value for a Label.
Label (string) - Allows to set a long string value for a Label.
Label (time) - Allows to set time for a Label
This Data Type is used by Document Types that are set to display as list views.
This Data Type is used by Media Types that are set to display as list views.
This Data Type is used by Member Types that are set to display as list views.
The picker opens a modal to pick a specific media item from the Media tree. The value saved is the selected media node UDI.
Displays a dropdown with all the available members. A single member can be selected. The value saved is the ID of the member.
This Data Type allows an editor to add an array of links. These can either be internal Umbraco pages external URLs or links to media in the Media section. The Data Type can be configured by limited number of links it is possible to add.
The picker opens a modal to pick multiple images from the Media tree. The value saved is a comma separated string of media node UDIs.
The picker opens a modal to pick multiple media items from the Media tree. The value saved is a comma separated string of media node UDIs.
A textbox to input a numeric value.
This Data type enables editors to choose from a list of radiobuttons.
The TinyMCE based WYSIWYG editor. This is the standard editor used to edit larger amount of text. The editor has a lot of settings, which can be changed on the Richtext editor Data Type in the Settings section.
In the default settings some tags such as bullet list can be used. If you want to use other tags like h1 or h2, you need to add stylesheets.
Create Rich Text Editor stylesheets for each tag(h1 or h2) and select them when configuring the Rich Text Editor Data Type. Learn more about how to configure this Data Type in the Rich Text Editor articles.
The "Style select" options need to be enabled in the toolbar section.
An example of the stylesheet tree is as follows:
A textbox that allows you to use multiple tags on a Document Type. You can specify a Tag Group for the Data Type, if you need to use Tags on different sections of your site.
A textarea provides a multi-line plain-text editing control. You can set the maximum allowed characters for the textarea and the number of rows, if any.
A normal HTML input text field.
A checkbox which saves either 0 or 1, depending on the checkbox being checked or not. A common use is to create a property with the 'umbracoNaviHide' alias and the Data Type True/False. This will provide editors with the option to hide nodes in the navigation menu on the website.
Adds an upload field, which allows documents or images to be uploaded to Umbraco. This does not add them to the media library, they are added to the document data.
There are five Upload Data Types:
Upload Article - Used for uploading and storing documents.
Upload Audio - Used for uploading and storing digital audio files.
Upload File - Used for uploading and storing different types of files in the Media section
Upload Vector Graphics - Used for uploading and storing Scalable Vector Graphics (svg) files which are text files containing source code to draw the desired image.
Upload Video - Used for uploading and storing video files.
