Nested Content (Legacy)
Last updated
Last updated
Alias: Umbraco.NestedContent
Returns: IEnumerable<IPublishedElement> (or IPublishedElement depending on configuration)
Nested Content is a list editing property editor, using Element Types to define the list item schema. By using Document Types you have the benefit of a reusable UI that you are familiar with and get to re-use all the standard Data Types as field editors. This property editor returns either a single item or a collection of this Document Type.
The Element Types that Nested Content uses are specialized Document Types - they can be found in the same section as Document Types. However, it is not possible to create content directly in the content tree with an Element Type - it is meant to be used in complex editors like Nested Content or Blocklist.
The Nested Content property editor is set-up/configured in the same way as any standard property editor, via the Data Types admin interface. To set-up your Nested Content property, create a new Data Type and select Nested Content from the list of available property editors.
You should then be presented with the Nested Content property editors Data Type editor as shown below.
The Data Type editor allows you to configure the following properties:
Doc Types - Defines a list of Document Types to use as data blueprints for this Nested Content instance. For each Document Type, you can provide the alias of the group you wish to render (the first group is used by default if not set) as well as a template for generating list item labels using the syntax {{propertyAlias}}.
If you would like to include the Document Type name in the label, you can use {{alias}}.
If you would like to include the index position in the label, you can use {{$index}}.
If your property links to a content, media or member node, you can use the Angular filter {{ pickerAlias | ncNodeName }} to show the node name rather than the node ID.
If your property is a rich text editor, you can use the Angular filter {{ pickerAlias | ncRichText }} to show the unformatted text.
You can use conditional logic to show text instead of 1 or 0 for a true/false property: {{checkboxPickerAlias == 1 ? 'Yes' : 'No'}}.
For more complex property types, you can display specific attributes by referencing the JSON attribute. For example, if using the MultiUrlPicker, show the name of the first link using {{urlPickerAlias[0]["name"]}}.
Min Items - Sets the minimum number of items that should be allowed in the list. If greater than 0, Nested Content will pre-populate your list with the minimum amount of allowed items and prevent deleting items below this level. Defaults to 0.
Max Items - Sets the maximum number of items that should be allowed in the list. If greater than 0, Nested Content will prevent new items being added to the list above this threshold. Defaults to 0.
Confirm Deletes - Enabling this will demand item deletions to require a confirmation before being deleted. Defaults to true.
Show Icons - Enabling this will display the item's Document Type icon next to the name in the Nested Content list.
Hide Label - Enabling this will hide the property editor's label and expand the Nested Content property editor to the full width of the editor window.
Once your Data Type has been configured, set-up a property on your page Document Type using your new Data Type and you are set to start editing.
There is a handful of editors that Nested Content does not support in its elements. These include:
When viewing a Nested Content editor for the first time, you'll be presented with an icon and help text to get you started.
Click the plus icon to start creating a new item in the list.
If your Nested Content editor is configured with multiple document-types you will be presented with a dialog window to select which Document Type you would like to use.
Click the icon of the Document Type you wish to use and a new item will be created in the list using that Document Type.
If you only have one Document Type configured for your Nested Content editor, then clicking the plus icon will not display the dialog and instead will jump straight to inserting an entry in the editor for you ready to edit.
More items can be added to the list by clicking the plus icon for each additional item.
To close the editor for an item or open the editor for another item in the list, you click the edit icon.
To reorder the list, click and drag the move icon up and down to place the items in the order you want.
To delete an item click the delete icon. If the minimum number of items is reached, then the delete icon will appear greyed out to prevent going below the minimum allowed number of items.
If Nested Content is configured with a minimum and maximum item of 1, then it goes into single item mode.
In single item mode, there is no icon displayed to add new items, and the single items editor will be open by default and its header bar removed.
In this mode, Nested Content works more like a fieldset than a list editor.
To render the stored value of your Nested Content property, a built in value converter is provided for you. Call the Value<T> method with a generic type of IEnumerable<IPublishedElement> and the stored value will be returned as a list of IPublishedElement entities.
Example:
Each item is treated as a standard IPublishedElement entity, which means you can use all the value converters you are used to using.
Example:
If your Nested Content property editor is configured in single item mode, then the value converter will automatically know this and return a single IPublishedElement entity rather than an IEnumerable<IPublishedElement> list. Therefore, when using Nested Content in single item mode, you can call Value<T> with a generic type of IPublishedElement and you can start accessing the entity's properties straight away, rather than having to then fetch it from a list first.
Example:
For the sake of this example, let us assume we have a Nested Content property with alias attendeeList, where the element Document Type has an alias of attendee. It has the Properties: user_name, user_email, join_time, leave_time, duration, phone.
To save data in Nested Content, we need to create a new C# List containing a Dictionary of type <string, object>. Dictionary<string, string> would also work. The first dictionary item property/parameter we should specify for each Nested Content element is ncContentTypeAlias, which is the alias of the Document Type that we have nested.
Afterwards, the entire list needs to be serialized to Json via JsonConvert.
In the above sample we iterate through a list of participants (the data for such participants could be coming from an API, for example), and add a new Dictionary item for each person in the list.
