Monday, November 20, 2017

Modifying the query template for the Highlighted Content modern web part – a very brittle solution


The highlighted content web part in modern pages is the successor for the content search web part. It does a pretty decent job, but people like me who like to tune what we get back want some more expert settings, much like we had in the content search web part.

In the highlighted content web part you can add multiple filters today, which are then joined with an OR. This is useful for many scenarios, but often you want to have AND to limit results instead. For example all sites with a specific title, and not all sites OR all items with a specific title.

The above scenario is one I just looked at, and I didn’t want to roll my own web part. Elio Struyf has a PnP sample search web part, but it doesn’t support the same visuals – and I’ll probably end up modifying this in the end ;) But that’s not for this post.

I decided to dig into the properties of the highlighted content web part, and turns out it has a property named advancedQueryText, which is the query template. This property is not included in the UI, but using for example PnP PowerShell you can set this.

The below JSON has a couple of modifications. I have added SiteLogo as an extra managed property to use when showing the result preview, and I have added KQL in the advancedQueryText property.


You can download the properties file from my GitHub repo and modify as needed:

The below PnP powershell creates a new page, and adds a web part with the properties specified.

$pageName = "Awesome"
Connect-PnPOnline -Url
Add-PnPClientSidePage -Name $pageName
$searchProps = Get-Content -Path .\searchprops.json -Raw
Add-PnPClientSideWebPart -Page $pageName -DefaultWebPartType ContentRollup -WebPartProperties $searchProps

The caveat is of course that if you edit the web part properties in the UI, everything breaks ;) Which means this is not 100% production ready yet. Hopefully the advancedQueryText property will make it’s way to the UI soon.



  1. Great post and nice discovery on the json properties of the highlighted content. I'm currently working doing this myself, but I'm struggle with the KQL portion, essentially im wanting to exclude two sites from the search (Site title != site1 AND Site tile != site2). How would I compose that?

    Additionally, I have found a method to update web parts in place with pnp powershell as well:

    $webparts = Get-PnPClientSideComponent -Page Page

    $customwebpart = $webparts[2] #Must manually define what webpart in the array you want to modify
    $customwebpartprops = $customwebpart.PropertiesJson | ConvertFrom-Json
    $customwebpartprops.query.advancedQueryText = "{searchterms} contentclass=sts_site sitetitle=hub:*"
    $customwebpartJSON = $customwebpartprops | ConvertTo-Json -Depth 100

    Set-PnPClientSideWebPart -Page Home -Identity $customwebpart.InstanceId -PropertiesJson $customwebpartJSON

    1. Find the siteid and do:

      -siteid:00000-000 -siteid:11111-111

      etc. That's the most efficient way.

  2. Thank you for sharing :). Great post. I have a question, may be bit off topic to original content of this post.
    Is there any way to show "all Modern Team sites where user is member of" using Highlighted content web part (in general, in KQL query)?.
    I am able to fetch "modern site where user has access to" using ContentClass=STS_Site AND WebTemplate=GROUP, but not able to find the right managed property to fetch "Site members".

  3. This post helped me alot as a starting point. I have discovered that there is an custom 'advanced' mode that supports CAML/KQL queries through the UI, if you set the querymode to 'advanced in the query template (.json file). I have documentated it here:

  4. That's pretty cool :-) Probably plans to open this up is my guess.