Discover the "Multilist with Search" Formula

Thursday, February 16, 2017 @ 03:30

By: Scott Gillis, Lead Consultant – I find myself wanting to leverage the "Multilist with Search" field often when architecting a site. The ability to provide the users with multiple pages of information to pick from, while having the ability to perform a wildcard search, makes it an excellent option for assigning taxonomy to a page or item. As many of the benefits are for the editor, the headaches of trying to recall the syntax to setup the source is always a pain for me. I spend an hour or so digging through old code snippets, notes, and Google looking for the right syntax formula.

But that shall be no more, as this post will serve as my notes for future setups and hopefully yours too.

The Setup

Let's say we have a product taxonomy which is made up of a series of nested folders for organizational purposes and a product can be assigned one or more categories. If we are building out taxonomy assignments for some products for our Coffeeshop, we may have a list of items in the content tree, such as

Product Categories Image

Our product template will be fairly simple and contain the following fields

Product Template Image

The field we are focused on is Product Taxonomy and how to properly point it at our taxonomy list, because we want to allow the editor to pick one or more of the categories.

Gut Instinct

Your initial gut instinct, or at least mine, is to begin wiring up Product Taxonomy with DataSource= to set the pick list like any of the other pick types, so our value would be

DataSource=/sitecore/content/GlobalSettingsAndData/ProductTaxonomy

Which ends up producing a list of everything. If you try and get fancy and use the item ID, you'll end up with the same results.
Data Source Sample Image

Start Search Location

The value we need to use is StartSearchLocation, which, by gut-feel, would use the path like this

StartSearchLocation=/sitecore/content/GlobalSettingsAndData/ProductTaxonomy

And this too sadly ends with a list of everything in the content tree. The natural progression of trial and error means to use the ID, so we have

StartSearchLocation={0A05923B-F8DA-4865-AE0A-D4288C70B0B6}

Start Search Only Image

Template Filter

Feeling a little better now, but it includes the sub-folders which have been setup that we want to not allow for selection. To limit what is available for selection, we can apply a second parameter appended via an ampersand ('&') to the source value. The addition is TemplateFilter, which accepts a list of pipe delimited ('|') template IDs.

In this sample, we want all Basic Setting items (7F289750-AA0F-49DB-B479-F7D4646061DB) and CSS Class items (B28694DA-2FE5-478E-A64F-AA918BA53796)
StartSearchLocation={0A05923B-F8DA-4865-AE0A-D4288C70B0B6}&TemplateFilter={7F289750-AA0F-49DB-B479-F7D4646061DB}|{B28694DA-2FE5-478E-A64F-AA918BA53796}

Template Filter Image

Page Size

If, for some reason, the default page size of 20 items doesn't fit your editor's needs, then there is an additional parameter that can be added, PageSize, which will limit the number of items shown.

In this sample, we only want to show 3 items per page.
StartSearchLocation={0A05923B-F8DA-4865-AE0A-D4288C70B0B6}&TemplateFilter={7F289750-AA0F-49DB-B479-F7D4646061DB}|{B28694DA-2FE5-478E-A64F-AA918BA53796}&PageSize=3

Page Size Image

Filter

In instances when you need to provide a very finely tuned list of items to pick for the editor, you can use the Filter parameter, which supports simple to very complex Lucene queries. When using the filter, you must include a plus or minus sign with the field indicating the appropriate inclusion (plus sign) or exclusion (minus sign) you wish to achieve.

In this example, we want to only show the taxonomy items that include the sub-string 'caff'
StartSearchLocation={0A05923B-F8DA-4865-AE0A-D4288C70B0B6}&TemplateFilter={7F289750-AA0F-49DB-B479-F7D4646061DB}|{B28694DA-2FE5-478E-A64F-AA918BA53796}&Filter=+_name:*caff*

Filter with Lucene Image

Sitecore Query

Finally, for those who have really complex needs we can perform our filter via a traditional Sitecore query. Just by assigning it to the StartSearchLocation value. When using this method, note that you need to be sure to convert '=' to '->' to have them properly translated by the system.

For this example, we only want the color items.
StartSearchLocation=query:/sitecore/content/GlobalSettingsAndData/ProductTaxonomy/*/*[@@templatename->'CSSClass']

Filter with Sitecore Query Image

You'll notice in the above image, only the first CSS Class item is being returned, which is Red. I have an open ticket with Sitecore Support (Issue ID 474858) asking for clarification whether this is a bug or how they expect us to use it. I'll update as they provide details.

But wait, there's more

When working on building the perfect source for your field and the field is always blank or you just keep getting the entire tree, be sure to check the log. Sitecore has provided some nice error logging to help you figure out what might need to be changed. These messages include

  • Content Editor - Multilist with search: Cannot find any item by query '{0}' from the StartSearchLocation parameter. Location: 'Source' field of the '{1}' field in the '{2}' template
  • Content Editor - Multilist with search: Query '{0}' from the StartSearchLocation parameter has incorrect format. Location: 'Source' field of the '{1}' field in the '{2}' template
  • Content Editor - Multilist with search: Cannot find any item by id '{0}' from the StartSearchLocation parameter. Location: 'Source' field of the '{1}' field in the '{2}' template. '{3}' will be used instead.
  • Content Editor - Multilist with search: Value '{0}' from the StartSearchLocation parameter could not be treated as a valid GUID. Location: 'Source' field of the '{1}' field in the '{2}' template. '{3}' will be used instead.

Finally, if you want to do some further exploring, the full source showing how the field parses the source into queries can be found using a little decompile magic on Sitecore.Buckets.dll, you'll be looking for the SearchList class.

 

 

Scott Gillis, Lead Consultant at Paragon and 2017 Sitecore MVP, has been working with Sitecore for several years. He has a deep passion for helping clients leverage their content and data into powerful new capabilities in Sitecore and has produced successful outcomes as the technical lead on numerous, complex implementations. Recently, Scott has been focusing on helping these clients take advantage of the wealth of data collected by Sitecore Experience Analytics.