PnP Modern Search Extensibility: Creating Web Components

In the last couple of blogs we looked at basics of PnP Modern Search Extensibility and how to add a custom layout, in this blog we will look at how to extend PnP Modern Search webparts by adding custom web components.

A Web component is a set of web platform APIs that allow you to create new custom, reusable, encapsulated HTML elements that can be used in your templates to implement complex behaviors. In this solution we use them here as "wrappers" for React components to be able to use them with Handlebars.

In the previous blog, we used <pnp-collapsible> built in web component, here is the complete list of built-in web components provided by PnP,

  1. <pnp-iconfile>
  2. <pnp-documentcard>
  3. <pnp-filepreview>
  4. <pnp-icon>
  5. <pnp-panel>
  6. <pnp-collapsible>
  7. <pnp-img>
  8. <pnp-breadcrumb>

In our example, we want to make changes to the People layout, we want to make it clickable and show pronouns beside the person’s name. We also want to define on which page user should be redirected when user clicks on the result using layout option property. We also want the pronouns and assistant to appear on the hover card.
So, here is the breakdown of the pieces that we would have to create,
  1. Create and register a custom persona web component based on PersonaWebComponent.
  2. Create and register a custom web component for hover card based on mgt-person-card.
  3. Create a custom layout class, corresponding HTML template and register the custom layout to make it available. 

How to create a Web component

Creation process consists of two steps:

  1. Create the web component logic and any sub components.
  2. Register the web component in the library class.

Create the web component logic and any sub components

To Create the Custom Persona web component we need to,

  1. A web component class that would implement BaseWebComponent. This class must at least have connectedCallback() implemented, which essentially loads our React Component (CustomPersonaComponent here). The resolveAttributes() method will look at all data-* HTML attributes in your web component custom element node and return a corresponding key/value pair object with values in their guessed type that you can pass directly to your React component as props.

  2. A React component,
    • The react component in our case is going to extend functionality of default PersonaWebComponent used by PnP Search and will also capture the Profile Page url and Pronouns properties passed to it from the handlebar template, so we will start with copying code for PersonaWebComponent (available at pnp-modern-search-extensibility\pnp-modern-search-main\search-parts\src\components\PersonaComponent.tsx).
    • We will change the class names for props, state and component classes to ICustomPersonaComponentProps, ICustomPersonaComponenState and CustomPersonaComponent respectively.
    • We will add pronouns and profilePageUrl props to our ICustomPersonalComponentProps

    • We will then make changes to onRenderPrimaryText method implementation to include pronouns beside the user display name and then we will add a <Link> around <Persona> and pass the profilePageUrl along with user’s email address.

  

To create a Custom Persona Card Component we need to,

  1. Similar to Custom Persona component we will create a web component class that would implement BaseWebComponent. This class must at least have connectedCallback() implemented. In addition to that, this class will also initialize the SPHttpClient and PageContext (available through BaseWebComponent) objects for us and pass them as additional props to the React component.                                                                                                                 
  2. In the React component,
    • This component will get the user’s pronouns and assistant email passed through Handlebar Layout (in turn passed through Web Component props) along with SPHttpClient and PageContext.                                                                                                                                         
    • In the SharePoint User profile the assistant field only stores the email property of the user selected, we will have resolve the email address to a display name using a REST API call on componentDidMount().
                                                      
    • The render() will create the Additional Details section that we want to appear on the card, the key here is the template=“additional-details” property which is used to add custom content to the additional details container.


Register the web component in the library class

To register the components in the library, we will override the getCustomWebComponents() and add details for both of these components.

Creating handlebar layout

To Create the Custom People handlebar layout we need to,

  1. We will create the custom-people.html and CustomPeopleLayout.ts files
  2. The custom-people.html is based on people.html form PnP package but we are going to lock down the people fields that means that the user won’t get following layout options but we do want to ask user for Profile Page url, so we will be adding that as an layout option,                                                                                                                  


  3. In the following screenshot,
    • When configuring <mgt-person> declaration we are saying person-card should appear on hover (person-card=”hover”)
    • When configuring <custom-persona> we are locking down the card size to be extra large (data-persona-size=”15”). As image, display name etc. fields are no longer configurable we are passing their values using layout slots expressions. We also pass value of Profile Page url layout option that we just configured. We also expect that a managed property would have been configured for  user's pronouns and would have been added as a layout slot so, we also pass it using the layout slot expression.
    • Lastly, we want our own custom person card <custom-person-card> to appear on hover, so, we declare that inside <template data-type=”person-card”> and we pass assistant email and pronouns as well.   

                                                                                        
  4. We simplify the CustomPeopleLayout.ts file to following,

  5. The only step that remains is to register Custom-People handlebar inside getCustomLayouts() method,

Comments

Post a Comment

Popular posts from this blog

PnP Modern Search Extensibility: Creating Custom Layouts

Image
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...
Read more

PnP Modern Search Extensibility: Creating Handlebar Helpers

Image
In the blog series of PnP Modern Search Extensibility we have looked at basics of  PnP Modern Search Extensibility , how to add a  custom layout  and how to add custom web components , in this blog we will look at creating custom handlebar helpers. With extensibility you can also create Handlebar helpers that can be used to in HTML templates or while configuring layout fields. There are a lot of handlebar helpers available for common scenarios as well. In the previous blog we created a Custom Simple List layout, and for showing Project Summary we were using the Summary slot mapped to HitHighlightedSummary, but what if you have created a custom column in the library and want to use it show Project Summary and you also want to truncate it at 180 characters and add ellipsis and then when the user expands the collapsible section you want to show the whole Project Summary. To do that, first of all we need a handlebar helper that would truncate and add ellipsis after...
Read more