In today's Sitecore Tip of the Day I will go over the new parameters for the Multilist with Search and Treelist with Search fields that were added in Sitecore 7.

Note that in this article, when I refer to a regular Treelist or Multilist, I am referring to the field without search.

Parameter Syntax

Treelist and Multilist parameters provide a means of specifying what is displayed and what is selectable in a selection pane of the field. These parameters are specified in the Source of the Treelist or Multilist (with or without search) fields, as an &-separated set of key-value pairs. For example, in the below, Foo and Hello are keys and Bar and World are their respective values:

Foo=Bar&Hello=World

Sometimes we may have parameters that have multiple values. If this is the case then we comma-delimit the values, like so:

Foo=Bar,Baz&Hello=World

Lastly, note that we do not need to do anything special for values with spaces in them. For example:

Foo=Bar&Baz=Hello World

Specifying the Root of the Items in a Treelist or Multilist

One of the most common uses of parameters for Multilist and Treelist fields (with or without search) is for specifying the root of the items that should be displayed in the selection pane. Note that both the parameter and the syntax of its value in the fields without search are different from those of the fields with search.

For Fields without Search

In a regular Multilist, this root item is the direct parent of the items that will be available for selection; in a regular Treelist, this root item is the the root of the branch that is visible in the selection pane, all descendants of which (direct or otherwise) will be available for selection. Note that the DataSource is just a "link" to the item that is to be used as the root, and as such should be a path to the item. For example, the DataSource for a regular Treelist or Multilist field that enables editors to select news items might be something like:

DataSource=/sitecore/content/home/news

If a this was specified as the DataSource for a regular Treelist, then a tree will be displayed in the field's selection pane with the root node being the /sitecore/content/home/news item. If this was specified as the DataSource for a regular Multilist, then all children of the /sitecore/content/home/news item would be displayed.

For Fields with Search

When working with a Multilist with Search or a Treelist with Search, the parameter for specifying the root item is different from that of the fields without search.

For the Multilist and Treelist with Search fields, the parameter for specifying the root item is the StartSearchLocation parameter. This this parameter should not have a path as its value, but rather the ID of the root item. For example, the StartSearchLocation for a Multilist or Treelist with Search should look something like:

StartSearchLocation={AE1726CA-5837-4517-A23B-9E32965EDF3C}

Note that the StartSearchLocation parameter is required, else other parameters will not function as expected.

Changing the StartSearchLocation for a Treelist Field on an Individual Item

The Treelist with Search field is very different from the regular Treelist field. For starters, notice that the Treelist with Search field is not actually a tree. Instead, it is actually the same as the Multilist with Search field, except that the content editors have the ability to override the StartSearchLocation on the item itself, using the text box shown in the image, below:

If you are, however, one of those people (like me) who wish that we could have our tree in the Treelist with Search, it may be worth noting that in one of their technical blogs (referenced below, for further reading), the Sitecore team stated that they chose to "de-prioritise" the tree view, but they did not say that they chose to do away with it. Fear not, as there is still hope after all! Updated July 16, 2014: As noted in my July 15th post, Sitecore has deprecated the Treelist with Search field in Sitecore 7.2, so it looks like we will not be getting a Multilist/Treelist with Search field with a tree-view. I have also referenced this update in the comments, below.

Further Constraining the Elements in the Selection Pane

DataSource and StartSearchLocationare not the only parameters that can be used to specify what elements display in the selection pane.

For Fields without Search

The following are all of the valid parameters for the regular Multilist and Treelist fields (descriptions taken from Sitecore's Data Definition Cookbook - referenced below):

1) DataSource: Root item

DataSource=/Sitecore/Content/Home/News Articles

Update: A colleague suggested that I also include an example of how to source multiple paths:

DataSource=/Sitecore/Content/Home/News Articles|/Sitecore/Content/Home/Events

2) DatabaseName: The name of the database containing the root item

DataSource=/Sitecore/Content/Home/News Articles&DatabaseName=master

3) IncludeTemplatesForSelection: Users can only select items based on this comma-separated list of data template names

DataSource=/sitecore/Content/Home/News Articles&IncludeTemplatesForSelection=Video Articles,Photojournalism Articles

4) ExcludeTemplatesForSelection: Users cannot select items based on this comma-separated list of data template names

DataSource=/sitecore/Content/Home/News Articles&ExcludeTemplatesForSelection=Newspaper Articles

5) IncludeTemplatesForDisplay: Users can view items based on this comma-separated list of data template names and IDs

DataSource=/sitecore/Content/Home/News Articles&IncludeTemplatesForDisplay=Video Articles,{AE1726CA-5837-4517-A23B-9E32965EDF3C}

6) ExcludeTemplatesForDisplay: Users cannot view items based on this comma-separated list of data template names and IDs

DataSource=/sitecore/Content/Home/News Articles&ExcludeTemplatesForDisplay={AE1726CA-5837-4517-A23B-9E32965EDF3C}

7) IncludeItemsForDisplay: Users can view items based on this comma-separated list of item names and IDs

DataSource=/sitecore/Content/Home/News Articles&IncludeItemsForDisplay=Boy Sell Business for Ten Million Dollars,{FZ193C8Q--4517-2FXA-R786965Q4DE8},Blogs Rising in Popularity

8) ExcludeItemsForDisplay: Users cannot view items based on this comma-separated list of item names and IDs

DataSource=/sitecore/Content/Home/News Articles&ExcludeItemsForDisplay={FZ193C8Q--4517-2FXA-R786965Q4DE8},Boy Sells Business for Ten Million Dollars

9) AllowMultipleSelection: If 'yes' (no quotes), users can select the same item more than once

DataSource=/sitecore/Content/Home/News Articles&AllowMultipleSelection=yes

Note that these may be combined (again, as an &-delimited list of parameters) or used individually.

For Fields with Search

The following descriptions and examples were taken directly from the Sitecore 7 Development Team's blog post, entitled Using the new Sitecore 7 Field Types:

1) Search anywhere in the content tree

StartSearchLocation={11111111-1111-1111-1111-111111111111}

2) Search only on a certain part of the content tree

StartSearchLocation={110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}&Filter=+_path:110d559fdea542ea9c1c8a5df7e70ef9

3) Search in two or more places of the content tree

StartSearchLocation={110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}&Filter=_path:110d559fdea542ea9c1c8a5df7e70ef9|_path:3d6658d8a0bf4e75b3e2d050fabcf4e1

4) Only search for a particular template - Sitecore Bug Found! See comments for more

StartSearchLocation={11111111-1111-1111-1111-111111111111}&Filter=+_templatename:sample item

5) Only search for 2 template types - Sitecore Bug Found! See comments for more

StartSearchLocation={11111111-1111-1111-1111-111111111111}&Filter=_templatename:sample item|_templatename:media folder

6) Field search

StartSearchLocation={11111111-1111-1111-1111-111111111111}&Filter=_name:sitecore

7) Field search (mandatory)

StartSearchLocation={11111111-1111-1111-1111-111111111111}&Filter=+_name:sitecore

8) Field search (must not have)

StartSearchLocation={11111111-1111-1111-1111-111111111111}&Filter=-_name:sitecore

9) Use Sitecore Query

StartSearchLocation=query:/sitecore/content/*[@@name -> 'Home']&Filter=+_name:sitecore

10) Dynamic Page Size

StartSearchLocation={0DE95AE4-41AB-4D01-9EB0-67441B7C2450}&Filter=_name:*&PageSize=2

11) Wildcard

StartSearchLocation={0DE95AE4-41AB-4D01-9EB0-67441B7C2450}&Filter=_name:*

12) Filter Version

StartSearchLocation={0DE95AE4-41AB-4D01-9EB0-67441B7C2450}&Filter=+version:2

13) Filter Language

StartSearchLocation={0DE95AE4-41AB-4D01-9EB0-67441B7C2450}&Filter=parsedlanguage:english

14) Sort (No Direction)

StartSearchLocation={0DE95AE4-41AB-4D01-9EB0-67441B7C2450}&Filter=_name:*&SortField=_name

15) Sort (With Direction)

StartSearchLocation={0DE95AE4-41AB-4D01-9EB0-67441B7C2450}&Filter=_name:*&SortField=_name[asc|desc]

Further Reading

• Mark Ursino's blog post, entitled Tame Your Sitecore Treelists: further information and discussion regarding constraining regular Multilist and Treelist fields
• Sitecore's Data Definition Cookbook: further information on Sitecore parameters for regular Multilist and Treelist fields
• The Sitecore 7 Development Team's technical blog, entitled Using the new Sitecore 7 Field Types: further information on Sitecore 7's Multilist and Treelist with Search fields, as well as the Query Builder and Query Datasource fields.
• Sitecore's Developer's Guide To Item Buckets and Search: further information on Sitecore 7's Multilist and Treelist with Search fields, as well as the Query Builder, Query Datasource fields, Buckets, and other search-related topics.

Note that all information in this post was taken from the above three sources.