PnP Modern Search Extensibility: Creating Custom Layouts

In the last blog we were looking at the basics of PnP Modern Search Extensibility, what we can customize  and how to create a the library component. In this blog, we will explore how to add custom layouts using extensibility. 

Right now, PnP Modern Search Results webpart provides you with these 5 layouts, Details List, Cards, Slider, List and People, which should be sufficient for simpler scanarios. In addition to that, it also allows you to customize the layout by editing the handlebar template using “edit result template” option under Custom layout, or you can create a custom handlebar file, upload it on SharePoint and then add its location in “Use an external template layout” option.

For example, you are setting up a Search Results page for showing projects. If you use the the default List layout, then the results would end up looking like in the image below, it shows page title, author, date modified, project summary and then what all tags the project has been tagged with.

What if we want show Project Title, Site, Project Summary, Project End Date, Client Code, whether this is a featured project or not by showing a star beside the Project Title. Also, what if we want to show more project details such as capabilities, issue areas, segments in expandable/collapsible section as show in these images?

This transformation can easily be done by either editing the result template or by creating a custom handlebar html file and then referencing it. But what if you want to create a custom layout and make it available as one of the Layout under “Available layouts”, so that if you have multiple people configuring PnP Search Results webpart, they can quickly pick the layout leaving little room for mistakes and ensuring consistency.

If you are following the blog series you already know that with PnP Modern Search Extensibility, you can create an SPFx library Project in which to create a custom layout,

• You will create layout class that will define property pane options.
• You will create the HTML template associated with the layout.
• Make this layout available by registering it in the getCustomLayouts() method of the library.

All these steps will be covered in more detail in this blog post: 

1. We will start by creating a layouts folder under src/libraries. As this is a custom layout that we are creating for modifying results user interface, we will create results folder under layouts. We will create one more folder depending on what the layout is supposed to do, for this example, we are modifying the basic List layout, so, we will create a folder customSimpleList.
2. As we are modifying the simple list layout, we will copy simple-list.html (HTML template file) and SimpleListLayout.ts (layout class) files from the main PnP solution (\pnp-modern-search-main\search-parts\src\layouts\results) to our customSimpleList folder.
3. Then we will rename the copied files to custom-simple-llst.html and CustomSimpleListLayout.ts. You will notice that layout class file has an interface that defines the layout properties and a class that implements the BaseLayout abstract class using layout properties interface. You will rename the interface to ICustomSimpleLayoutProperties and class to CustomSimpleListLayout.
   

   
   
   
4. In the copied layout class file you will notice that to render labels concept of string localization has been used, you will have to define the corresponding strings in your mystrings.d.ts and en-us.js files and update the import of strings to import * as strings from "SampleExtensibilityLibraryLibraryStrings";

   

   

   
5. Then we will modify the custom-simple-list.html to match the expected results, for example, to add the star next to the Title, we will add the following code that can be seen in the white rectangle.

   

   
   
6. We will use <pnp-collapsible> one of the built in web component provided by PnP to render expandable/collapsible section,

   
7. Last step is to register the layout in getCustomLayouts() method by defining,
• Friendly name of the layout that will show up in the tiles.
• An Office UI Fabric icon for the layout.
• Unique key for the layout.
• Type of the layout, here you would select LayoutType.Result, as we have written this to modify the user interface of the search results.
• For template content you will have to provide path to the Layout HTML file.
• And with Service Key the layout class will get instantiated with the name given as first argument.

8. Then you would bundle, package, and deploy the solution as usual and register it with the search results webpart if you have not already (as part of part one of this blog series)
9. If you would want to write the layout class and HTML from scratch then you can follow steps defined here.