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 StartSearchLocation
are 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.