Multilist with Search Secret Sauce

Discover the Multilist with Search Formula

I find myself wanting to leverage the Multilist with Search field often when architecting a site. The ability to provide the users 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 the benefits are for the editor, the headaches 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 is to be no more, as this post will be my notes for future setup 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. If we are building out taxonomy assignments for some products for our Coffeeshop, we may have list of items in the content tree, such as

Product Category Taxonomy

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

Product Template

The field we are focused on is Product Taxonomy and how to properly point it at our taxonomy list as we want to allow the editor to pick one or more 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.)
DataSource source

Start Search Location

The value we need to use is StartSearchLocation, which always points to a single item whose chidren and grand-children and great-*-grandchildren will be filterd and displayed. My gut feel would use a path like

StartSearchLocation=/sitecore/content/GlobalSettingsAndData/ProductTaxonomy

And this to 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}

StartSearchLocation

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

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

PageSize

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

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. StartSearchLocation always needs to point to a single item of which the children will be selected and filtered for displaying.For this example, we only want the color items only, we could achieve this by filtering for specific items, or for the parent folder

StartSearchLocation=query:/sitecore/content/GlobalSettingsAndData/ProductTaxonomy/*/*[@@templatename->’CSSClass’]

Filter with a Sitecore Query

 

But wait there is some 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 to how the field parses the source into queries can be found with a little decompile magic of Sitecore.Buckets.dll, you’ll be looking for the SearchList class.

 

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s