Modern Page Web Part Provisioning

During a recent project, I needed to provision several new modern Home pages for multiple SharePoint communication sites in O365 and include a modern page web part (Highlighted Content Web Part, we’ll use HCWP) on each page which displayed all the recent pages within each site. Since the HCWP defaults to showing “Most Recent Documents“, I had to programmatically change the Type option from Documents to Pages. The object model for these new web parts is not fully detailed, so finding how to change the Type option to Pages involved a combination of techniques that I will detail next.

Determining HCWP Property Values

After much research and many trials, the easiest way to get the property values for the Highlighted Content Web Part is to first manually create the HCWP with the exact desired property settings. I used my O365 dev tenant to create a new SharePoint Communications Site, and then add a new page manually. Then I added a new HCWP web part as seen below in edit mode:

In this example, I modified the Type property to Pages instead of Documents (the default setting). Once the page and HCWP were setup as desired, I wrote a quick Windows Form Application that loads this existing Home.aspx page programmatically, but you can use any technique that will call this code:

Where url = https://{TenantName}{SiteName} and you are using a username with access to the page. Below is the loadPage method, where you can hover over the pageTest ClientSidePage object to view its properties.

Below is a screen shot of hovering over the pageTest object, in debug mode, to see all the Controls on the page. In this example, Control [1] is the Highlighted Content Web Part control.

If you expand that HCWP control ([1]), you see the “Properties” for the control:

Then under the Properties for this HCWP control, you can copy out the Root property to get the JSON value of all the HCWP control properties:

From within the Root JSON string, I pulled out the “query” property value to be used in code later:

“query”: { “contentLocation”: 1, “contentTypes”: [ 2 ], “sortType”: 1, “filters”: [ { “filterType”: 1, “value”: “” } ], “documentTypes”: [], “advancedQueryText”: “” },

In my case, I did have to remove one outer pair of curly brackets before JSON Viewer recognized the text as valid JSON. Below is a comparison of this Root JSON for 2 different HCWPs on 2 different pages. The HCWP on the left side is the default settings when a new HCWP is added to a page, and the HCWP on the right side is the one I added and then manually changed only the Type property to ‘Pages’ in the UI. All the differences in values are highlighted in yellow. As you can see, one quick change in the UI can result in several changes in the actual web part properties.

Provisioning new pages with HCWPs that display Recent Pages

Now I can use the information I obtained above to write the provisioning code. Below is the actual code, where a new HCWP web part control is created and added to a new modern page (Home.aspx). Notice the “query” property, as well as the “displayMaps” property, contain json content. I was able to use the string obtained from the debug hover windows and set the updated “query” value by parsing and converting the debug string value into a JSON object.

Note that in C#, I had to escape the double quote character by making the following changes:


"query": { "contentLocation": 1, "contentTypes": [ 2 ], "sortType": 1, "filters": [ { "filterType": 1, "value": "" } ], "documentTypes": [], "advancedQueryText": "" },


var jsonString = @"{""contentLocation"": 1,""contentTypes"": [2],""sortType"": 1,""filters"": [{""filterType"": 1,""value"": """"}],""documentTypes"": [],""advancedQueryText"": """"}";

With the double quotes escaped, the jsonString can be parsed into the query JSON object like so:

Newtonsoft.Json.Linq.JObject jObj = Newtonsoft.Json.Linq.JObject.Parse(jsonString);

highlightedContentWp.Properties["query"] = jObj;

Below is a screenshot of the code for adding the HCWP to a new modern page (note: the displayMaps property value is cut off in the screen shot, but you can use the instructions above to get the complete value):

Another side note: we set the title property for this new web part even though it was not part of the original default properties list from the debug session.

Since the object model is not well documented, I have found it easier to set up the modern page web part on a test page with the desired properties selected from the UI and then view that version of the web part in debug mode to get the actual properties that should be set. Using the code example above shows how to handle web part properties that include string, integer, Boolean, and json object types. This approach should apply to other web parts on modern pages and allow you to provision your various web parts as needed.

Share and Enjoy !

Related Content: