The treelist is a widely used multi-select Sitecore template field type. It enables the user to select any number of items from the Sitecore content tree. If you don't define a root item for the treelist, it will simply use the Sitecore-item as the root. The user can then navigate the content tree and select any items they desire. In some cases this might be fine. But more often than not, we can improve the user experience by simply setting a more suited root item in the treelists source property:
/Sitecore/Content/Home
This would set the home-item as the root of the treelist, so that the content author would only be able to navigate to and select items that are descendants of the home-item.
We can do a lot better than just setting a root item though. By defining a parameterized datasource, we can control what items are visible in the treelist, what items the user can select and more.
Building a treelist datasource
A simple treelist datasource, setting the root item of the treelist could look like this:DataSource=/Sitecore/Content/Home
Notice that we have simply prefixed the normal root item path with "DataSource=". If we simply need to set a root item, we can do it either way, as the result for the content authors would be the same. However, by converting the normal path to a datasource, we can now append a number of parameters to the source property.
Say we have a news section on our website, and all the news stories are organized in a folder structure in Sitecore. On our front page, we have a dedicated area for displaying important news stories. The news stories displayed on the front page are selected in a treelist.
All the folders are based on the NewsFolder-template, and the news items are based on the NewsStory-template. Now, if we simply set the root item to be the top folder in the news structure. One of our content authors could by mistake select one of the news folders in the treelist. This could cause some confusion for the content authors, as they could then have a treelist with e.g. 5 items selected, but only 4 news stories shown on the front page. Furthermore, if our code isn't written to be able to handle the selection of a news folder item, the front page might break.
Luckily we can avoid this situation all together, by simply defining what templates can be selected in the treelist. To do this, we simply need to append a parameter to the datasource:
DataSource=/Sitecore/Content/Home/News&IncludeTemplatesForSelection=NewsStory
By setting the IncludeTemplatesForSelection-parameter, we have limited our content authors to only be able to select items based on the NewsStory-template.
The structure of a treelist datasource
The treelist datasource consists of a path and a number of parameters. The parameters are key=value pairs separated by ampersand "&". The value part of the key=value pairs, can both be a single value and a comma-separated list.If the news structure from before also has a number of other items, besides the ones based on the NewsFolder-template and the NewsStory-template, and these are irrelevant in our treelist.
We can then simply filter these out by either using a blacklist (ExcludeTemplatesForDisplay) or a whitelist (IncludeTemplatesForDisplay) for determining which templates should be visible in our treelist.
DataSource=/Sitecore/Content/Home/News&IncludeTemplatesForSelection=NewsStory&IncludeTemplatesForDisplay=NewsFolder,NewsStory
Treelist parameters
DataSource
Path to the root item of the treelist.The root of the subtree that the content author will be able to navigate in the treelist.
DatabaseName
The name of the database containing the path defined in DataSource.IncludeTemplatesForSelection
A comma-separated list of template names or ID's. The content author will only be able to select items based on the templates defined in this parameter.ExcludeTemplatesForSelection
A comma-separated list of template names or ID's. The content author will be able to select items based on all templates except the templates defined in this parameter.IncludeTemplatesForDisplay
A comma-separated list of template names or ID's. Only items based on templates defined in this parameter will be shown in the treelist.ExcludeTemplatesForDisplay
A comma-separated list of template names or ID's. All items based on the templates from this parameter, will be hidden from the treelist.IncludeItemsForDisplay
A comma-separated list of item names and ID's. Only items from this parameter will be shown in the treelist.ExcludeItemsForDisplay
A comma-separated list of item names and ID's. Items from this parameter will be hidden in the treelist.AllowMultipleSelection
Determines if the content author can select the same item more than once.Notice, this is not a boolean value. To enable multiple selection, this parameter need to be set to "yes".
Example: DataSource=/Sitecore/Content/Home/News&IncludeTemplatesForSelection=NewsStory&AllowMultipleSelection=yes
