Have you ever wished for more flexible content options in the SharePoint Highlighted Content Web Part? Now you can add a custom query to retrieve the specific content you want to display on your modern SharePoint page!
We’ve written previously about the Highlighted Content Web Part (HCWP), so you can read this post about all of the other configuration options. Custom Query is a new option at the top of the HCWP configuration panel. When you configure a HCWP now, you must first select whether to apply filtering, or a custom query. If you select Filter, then you get all of the Content source/type, and filter/sort options we described in our previous article. If you select Custom Query, then you need to specify the exact query to obtain the results you wish.
KQL versus CAML
The syntax of the query you write depends on the scope of the content you wish to aggregate. If the scope is site-based, then you must use KQL (Keyword Query Language), the same query language you can use with SharePoint Search. If the scope is library based, then the query needs to use the CAML (Collaborative Application Markup Language) schema, which has been around in SharePoint for years. See the Microsoft reference links at the end of this article for documentation of the two query types.
More specifically, here are the source entries (scopes) to which you can currently apply a custom query, and which syntax is required for each:
KQL: This site, This site collection, All sites in the hub (if you are working in a hub site), Select sites, All sites
CAML: A document library on this site, The page library on this site. So this is not an aggregation at all, but just a filter of items from a single (specific) library on the current site.
Let’s look at some examples.
KQL example
When not using a Custom Query, HCWP filtering operations are as follows: Filters of the same type use an OR operator, and filters of different types use an AND operator. So it would not be possible to filter content based on the combination of two different managed properties.
Say, for example, you wish to display SharePoint Tasks which are High Priority and assigned to you (the current user). Using the standard HCWP filter, you can select the Tasks list type, but you can only filter by Assigned To and Priority by using the appropriate Managed Properties. And when specifying two Managed Property filters, the HCWP would retrieve tasks which were either assigned to the current user OR high priority, so you would get more results than you wished for.
Now, you can write a KQL query which retrieves items which meet both criteria.
Note that the HCWP still only displays the item’s Title and Modified date, so you need to trust that the correct filters are being applied. But this new query functionality gives you a lot more flexibility in displaying the appropriate content.
By the way, if you’d like to see how to do something similar without needing to understand SharePoint Managed Properties or KQL syntax (and also display any columns you wish), take a look at this Lightning Conductor tutorial video.
CAML example
The CAML queries are used to retrieve documents or pages in the Highlighted Content Web Part. It’s not possible to retrieve items from other types of lists such as custom lists, tasks, or events. For those, you would need to use the KQL query and filter by the content type, as shown above. The CAML schema allows you to not only specify criteria with which to retrieve items, but also gives you the ability to sort and group.
An example of a CAML query to display Word documents from the current site’s Documents library, which were created by the current user, would be:
<Query>
<Where>
<And>
<Eq>
<FieldRef Name="Author"/>
<Value Type="Integer">
<UserID/></Value>
</Eq>
<Eq>
<FieldRef Name="DocIcon"/>
<Value Type="Text">docx</Value>
</Eq>
</And>
</Where>
</Query>
However, at the time of this writing, the new CAML query feature does not seem to be quite working yet. And since it does not aggregate items from multiple libraries, you might be better off creating a View within your document library which filters, sorts, and groups as you require, and then use the Document library web part to display that specific view on your page.
We’ll update this post when the CAML query feature becomes functional. Feel free to follow us on Twitter or Like our Facebook page, where we often post about SharePoint updates, including updates to our website articles.
In closing
One thing to note in both of these custom query types, there is no help provided such as intellisense, or error messages if you have the syntax slightly wrong; you just don’t get any results (or all items, depending on the way in which it’s incorrect). So it’s not very user-friendly for an average business user – at least not at this point.
References:
