Tame Your Sitecore Treelists

Jan 21, 2011 by Mark Ursino

Posted under: Sitecore

One of the Sitecore template field types commonly used to select more than one item in a multi-tiered folder structure is the treelist. Though treelists work well by just defining a source path to start at, there are additional parameters that can be used to really tame them to avoid user error from content editors. This article will go over the optional parameters and how they can best be leveraged.

What is a Treelist?

Ahem… ok, back up. First let me quickly explain what a treelist is and how it can be quite useful. A treelist is a multi-select field that allows editors to pick from a tree of items (like the content tree itself). Treelists are useful when editors need the ability to pick more than one item and need to look at items in an n-tier structure (i.e. not on a single axis).

Like other fields types, a treelist can be given a path for its source which will define what item to start at when the field is used in a template. This is nice but it only defines the starting location of the tree — it does not define what sub-items can and cannot be clicked nor does it define what template types to even show.

Consider the sample below. Say you want to select employee items into a field but the employees themselves are separated by folders. By just setting a root path content editors can mistakenly select folders in addition to the desired employee items:

Enter treelist parameters…

Treelist Parameters

The optional treelist source parameters are meant to allow data definition titans the ability to specify what editors can do with the treelist.

Parameter Syntax

Treelist parameters are key-value pairs so they’re separated by the “&” and set with the “=” as expected. Also, for any comma-separated values, do not use single or double quotes around the values.

Invalid:

IncludeTemplatesForSelection="landing page", "generic page"

Valid:

IncludeTemplatesForSelection=landing page,generic page

DataSource

This is like a regular source you would define as a root item to start at. This is literally the root of the tree.

Example:

DataSource=/sitecore/content/home/employees

DatabaseName

This defines the name of the database to populate the tree with.

IncludeTemplatesForSelection

This is a comma-separated list of template names that should be allowed for selection. If this is defined, only items of templates defined in this list can be selected.

Example:

DataSource=/sitecore/content/home/employees&IncludeTemplatesForSelection=Employee

ExcludeTemplatesForSelection

This is a comma-separated list of template names that should NOT be allowed for selection. These items may need to appear in the treelist to show sub-items, but these cannot actually be selected.

The example below improves the original example by disallowing folders from selection and thus only allowing editors to select employees:

DataSource=/sitecore/content/home/employees&ExcludeTemplatesForSelection=Folder

IncludeTemplatesForDisplay

This is a comma-separated list of template names that should be displayed in the treelist. If this is defined, only items of templates defined in this list can be displayed. An important thing to note here is that for any templates in this list, the parent items must at least be displayed in the treelist in order for these to show up.

DataSource=/sitecore/content/home/employees&IncludeTemplatesForDisplay=Employee

ExcludeTemplatesForDisplay

This is a comma-separated list of template names that should NOT be displayed in the treelist. Any sub-items of these templates will also not display because these are hidden.

IncludeItemsForDisplay

This is a comma-separated list of GUIDs that should be displayed. This is useful to define specific items by their GUIDs.

ExcludeItemsForDisplay

This is a comma-separated list of GUIDs that should NOT be displayed. This is useful to define specific items by their GUIDs.

AllowMultipleSelection

This defines whether or not an editor can select the same item more than once. Interestingly, this is not a boolean but rather the word yes.

Example:

DataSource=/sitecore/content/home/employees&AllowMultipleSelection=yes

Additional Reading

Hopefully the examples above provides some useful scenarios to understand parameters. Everything I’ve mentioned here is covered in official Sitecore documentation in the Data Definition Cookbook on the SDN. Yan Sklyarenko also has a post on how to validate the source of a treelist which is an excellent tool with all these long obscure source parameters!

13 Comments + Add Comment

Tweets that mention Tame Your Sitecore Treelists | Fire Breaks Ice -- Topsy.com January 21, 2011 at 8:49 am

[...] This post was mentioned on Twitter by Matt Schweers, firebreaksice. firebreaksice said: New post: Tame Your Sitecore Treelists http://j.mp/gACWw8 #sitecore [...]

Reply
Yan Sklyarenko January 21, 2011 at 10:09 am

Nice post! Some time ago I blogged about how to use field validation to validate the source of the treelist: http://ysdevlog.blogspot.com/2009/03/validating-source-of-treelist.html. You might find it useful

Reply
Mark Ursino January 21, 2011 at 10:32 am

Ahhh, awesome Yan. Very useful. I’ve added a link to your post which I’m sure will definitely come in handy.

Reply
Jaap July 29, 2011 at 11:37 am

Nice, I was actually looking for a way to filter multi select boxes but this is nice to know just as much!

Reply
Setting the Folder in the sitecore TreeList control | Paul's Sitecore Musings August 8, 2011 at 1:59 pm

[...] things through the “Source” property as detailed in Sitecore’s documentation (and here). However, one setting that (I feel) is missing is the ability to specify which tree node to start [...]

Reply
mark stiles August 22, 2011 at 12:42 pm

I noticed that it didn’t work on the DropTree field. Not sure if that was just an oversight or what. There’s not a whole lot of uniformity in the datasource for fields. Great article aside from that.

Reply
Doug Couto December 13, 2011 at 1:59 pm

Very nice post Mark! Thank you for sharing!

Reply
Corneliu March 19, 2012 at 4:00 pm

Great article. Any way to filter what can be selected (not just what can be displayed) by GUIDs?

I’ve got a hierarchy of nodes that are all the same type, but want children of certain nodes to be selectable (not their parents).

If only there were an “ExcludeItemsForSelection” parameter…

Reply
Corneliu March 20, 2012 at 3:03 pm

Wound up getting around this by creating a custom validator and applying it to the treelist field.

Reply
Sam September 30, 2012 at 7:22 pm

Hi! In Sitecore admin, a treelist it can be consing when selecting an item with the same name under a different parent. Is there any way to display the parent item name along with the selected child item name in the right handside column?

Reply
Sitecore query for fields and custom TreeListEx control to support queries | a thousand lines of code October 24, 2012 at 5:57 pm

[...] along with the path and it uses the parameters to filter the resulting list. Mark Ursino has a really good blog post on its [...]

Reply
Ruud van Falier December 12, 2012 at 4:09 am

I want to comment on the fact that you cannot use GUIDs to include/exclude templates.
It was supposed to be supported and if you look at the code using Reflector or DotPeek you will see they have written some code for that.
The problem is that they lowercase everything before they add it to the Sitecore query that eventually retrieves the items that are displayed in the ‘selected’ listbox.
Because of that, selection by GUID doesn’t work as they are always uppercase in the Sitecore item XML and thus the query will never match any of them.

This bug has been reported to Sitecore so I except GUID selection to be supported in future releases.

Reply
anonymous April 9, 2013 at 11:09 am

Nice post. Thanks.
Is there anyway multiple items can be selected that have been selected in the treelist in order to sort them?

Reply