Sitecore bug found in Sitecore 8.1 Update 2 when trying to use IDs with tbe IncludeTemplatesForDisplay and ExcludeTemplatesForDisplay Treelist field parameters.
I prefer to use template IDs vs template names in my Treelist datasources, as IDs are more reliable and will not break if/when a template is renamed. Unfortunatley, I could not seem to get template IDs to work properly with my treelist field's IncludeTemplatesForDisplay and ExcludeTemplatesForDisplay parameters, in my Sitecore 8.1 Update 2 solution. I knew that I was doing everything correctly, so I created a test instance and started to investigate.
To investigate the issue, I installed a clean instance of Sitecore 8.1 update 2 and created a tree structure that looks similar to the following:
---v content - (Parent: sitecore)
-----v home - (Parent: content)
-------- about-us - (Parent: home)
-------v test folder 1 - (Parent: home)
--------- foo 1
--------- foo 2
--------- foo 3
-------v test folder 2 - (Parent: home)
--------- foo 4
--------- foo 5
--------- foo 6
In this example, "test folder 1" and "test folder 2" items have the Foo Folder template, and all of the "foo X" items have the Foo template.
On my "about-us" item's template, I added a Treelist field and set it's datasource to the following:
When I added the above datasource, only the "home" item displayed in the selection pane. I removed the IncludeTemplatesForDisplay parameter and everything under the home item showed. I then changed the datasource to the following and tested:
This worked: the "home" item, the "test folder X" items and all of the "foo Y" items displayed in the treelist.
I opened up Sitecore.Kernel and had a look at the Sitecore.Shell.Applications.ContentEditor.TreeList class (the backing class for the TreeList field type). In the control's OnLoad method, the TreeViewEx's (view for the control's) DataContext (object holding items to be displayed) is created and it's Filter property (determines what items to filter from display) was set to the returned value (string) of the private method FormTemplateFilterForDisplay(). This method is responsible for parsing the values of the [Include/Exclude][Templates|Items]ForDisplay parameters of the field's datasource. I noticed that near the beginning of the method, the values of the IncludeTemplatesForDisplay and ExcludeTemplatesForDisplay parameters are both being lower-cased (culture invariant) before being parsed into the queries that filter items from display. Since I already knew that you cannot use lower-cased guids in Sitecore queries (can be verified by running a Sitecore query with a lower-case guid), this seemed odd to me, since there are many sources of documentation online (including a blog post that I wrote a long time ago, and Sitecore's own documentation), that explicitly state that these parameters accept a comma-separated list of template IDs or item names.
The next thing that I did was repeat all my tests using ExcludeTemplatesForDisplay and sure enough it had the same problem with template IDs but worked with template names. I then tested with the IncludeItemsForDisplay and the ExcludeItemsForDisplay parameters, and verified that they worked correctly, since they were not being lower-cased before being parsed into queries. As expected, they worked correctly.
Finally, I validated my hypothesis by writing a new CustomTreeList that extends the TreeList class and overrides the OnLoad method. I called all the same logic as the TreeList class (via base.OnLoad(args)), and then removed the DataContext control from its TreeviewEx. I then made my own version of the FormTemplateFilterForDisplay() method, which was the same as the original, only with the two calls that lower-case (culture-invariant) the IncludeTemplatesForDisplay and ExcludeTemplatesForDisplay parameters removed. This way, the values held by those parameters would not be lower-cased before being parsed into the filter queries. I then compiled and added all of the necessary configuration and the new Field Type item in the Core DB, in order to be able to use my new field type. I then added my original datasource back in:
As expected, the above datasource worked as expected with the new field type, but not with the OOTB one. I sent my findings over to Sitecore Support to report as a bug and to get an official patch.
Sitecore Support confirmed the issue as a bug and that I had correctly identified the source of the issue. They assigned the bug reference number 90652, and were kind enough to provide me with the following patch (note that both of the attached files mentioned below are in the zip attached to this post):
More information about public reference numbers can be found here: