Personalizing Search Experiences with Blueprints

As we saw in the previous lesson, using search facets is great in providing visitors a way to quickly filter search results. However, Clarity has some search use cases that they wish to further customize and personalize. Liferay’s Search Blueprints provide the necessary tools to meet Clarity’s customization needs.

Use Blueprints to define implicit search criteria that can be added to any user’s search query to help enhance the search experience. Blueprints offers a UI-based configuration experience where search criteria is set by dragging and dropping elements. Use Blueprints to boost, filter, or even hide specific search results. Apply a different Blueprint to each search results page, or leverage your Blueprints with headless APIs.

Complete the following exercises to better understand the capabilities of Search Blueprints.

Exercise: Customizing Search Results with Search Blueprints

Here you’ll revisit the Open Positions results page and create a Search Blueprint to only return recent job listing articles as the Clarity Admin user.

To do this,

1. Sign in as the Clarity Admin user.

   • Username: [e-mail]
   • Password: learn

2. Open the Site Menu (), expand Content and Data, and select Web Content.

3. Click on the Structures tab and click Job Listing. In the very right, click the Properties () icon. Take note of the Structure Key ID (i.e. 34060).

4. Open the Global Menu (), navigate to Applications → Blueprints.

5. Click the add button to add a new search blueprint. Enter Job Listings Last 60 Days as the title and click Create.

6. In the right menu of query elements, expand the FILTER section and find the Filter by Exact Terms Match element. Click Add for the element.

7. In the Field field, enter ddmStructureKey. In the Values field, enter the Structure Key ID of the job listing web content structure (e.g. 34060).

   

8. In the left navigation, click Query Settings.

9. Click Selected Types and click Select Asset Types.

10. Select Web Content Article and click Done.

11. In the top menu, click Preview to preview the Search Blueprint in action. For example, search for the term Developer to see developer related results.

12. Click Add () to add another query element above the first one.

13. Expand the CUSTOM section and find the Custom JSON Element element. Click Add for the element.

14. From the training workspace, go to the [repository-folder]/exercises/lesson-18/ folder and open the filter-last-60d.json file on your machine.

15. Replace the sample code in the JSON Text Area with the data from the file.

    

16. In the top menu, click Preview to preview the Search Blueprint in action. For example, search for the term Developer to see developer related results. In the custom JSON element try editing the logic by changing now-60d to now-1d. Try another preview search.

17. Change the JSON element back to now-60d. Click Save.

Edit the Open Positions Page to use the search blueprints.

1. Navigate to the Open Positions page (i.e. Careers → Open Positions). In the top menubar, click the edit page () icon.

2. From the Fragments and Widgets menu, drag and drop a Blueprints Options widget to the bottom of the page below the Search Options widget.

3. Click the Actions menu () and select Configuration. Click Select to choose a search blueprint.

4. Click Select for the Job Listings Last 60 Days blueprint. Click Save and close the window.

5. Note, we can now remove the search Type Facet widget that filters for web content articles. The search Custom Filter widget that filters for job listing web content can also be removed.

6. Click Publish. The search results now only show job listings that were created in the last 60 days.

Great! You’ve created two search blueprints and applied them in the Open Positions page as an alternative to the Custom Filter widget you added in a previous exercise.

Next, you’ll learn how to use search blueprints with collection providers.

Exercise: Dynamic Collections with Search Blueprints

One simple way to leverage search blueprints is with collection providers. Every time you create a search blueprint, a collection provider is automatically generated. Then, showing the results of the search blueprint is as easy as adding a collection display widget onto a site page. For example, Clarity wants to have a site page that automatically displays a list of upcoming events. A search blueprint can query upcoming events on their calendar to automatically fetch these upcoming events. While logged in as the Clarity Admin user, follow these steps to see how this works.

1. Create a site page with a calendar widget.

   1. From the Site Menu (), navigate to Site Builder → Pages.

   2. Click New and select Page.

   3. Select Primary Master Page.

   4. Enter Calendar as the name and click Add.

   5. Select Fragments and Widgets in the left menu and select the Widgets tab. Scroll down to the Collaboration section and drag a Calendar widget onto the page. Click Publish.

   6. In the list of site pages, find the calendar page you just created, click the options icon and select View.

   7. Select the Month view and click on any date that is before your current date and enter Past Event 1 as the name and click Save.

   8. Click on any date that is after your current date and enter Future Event 1 as the name and click Save.

   9. Add one more event after Future Event 1 and enter Future Event 2 as the name and click Save.

      

2. Enable the Collections with Search Blueprints feature flag.

   1. Open the Global Menu (), navigate to Control Panel → Instance Settings.

   2. Click Feature Flags and select Beta in the left navigation. Enable Collections with Search Blueprints (LPS-129412).

3. Create a future events Search Blueprints Element.

   1. From the Global Menu, navigate to Applications → Blueprints.

   2. Click on the Elements tab and click Add.

   3. Enter Future Events as the title and click Create.

   4. From the training workspace, go to the [repository-folder]/exercises/lesson-18/ folder and open the filter-future-events.json file on your machine.

   5. Replace the sample JSON with the data from the file.

   6. Click Save.

4. Create a future events Search Blueprint.

   1. Still in the search blueprints application, click on the Blueprints tab.

   2. Click Add to create a new blueprint. Enter Future Events as the name and click Create.

   3. In the right menu of query elements, expand the FILTER section and find the Future Events element you created in the previous step. Click Add for the element.

   4. In the left navigation, click Query Settings. Change the searchable type to Selected Types. Click Select Asset Types and check Calendar Event and click Done.

      

   5. Click Save for the blueprint.

5. Create a future events site page with a collection provider.

   1. From the Site Menu (), navigate to Site Builder → Pages.

   2. Click New and select Page.

   3. Select Primary Master Page.

   4. Enter Future Events as the name and click Add.

   5. Select Fragments and Widgets in the left menu and select the Fragments tab. In the search bar, search for collection and find the Collection Display fragment. Drag the fragment onto the page.

   6. Click on the Collection Display fragment you just added. In the configuration menu on the right, click Select Collection ().

   7. In the new window select the Collection Providers tab. Select the Future Events collection provider.

   8. Under style display, select Bulleted List.

   9. Click Publish.

      

      The search blueprint automatically provides a collection of future events.

You now have created and configured a search blueprint that uses a collection provider to display future calendar events.

Next, you’ll learn how to leverage search blueprints with custom fields, then query the fields in Liferay’s headless APIs.

Exercise: Search Blueprints with Custom Fields

Occasionally businesses need to integrate with other web services. For example, the employee benefits system Clarity utilizes wants to reference Clarity employees based on the registration ID numbers the service uses. In Liferay, a custom field can be added to user accounts to add this additional field. Then Liferay’s headless APIs can be used to query this custom field. While logged in as the Clarity Admin user, follow the steps below to see this in action.

Note: The user account headless APIs cannot filter for custom fields directly. Therefore, a search blueprint is leveraged to be able to query for this custom field.

1. From the Global Menu, go to Control Panel → Custom Fields.

2. Select User and click New to begin creating a custom field.

3. Select Input Field and enter these details.

   Field	Value
   Field Name	RegistrationId
   Data Type	Integer

4. Click Save.

5. From the Global Menu, go to Control Panel → Users & Organizations.

6. Select Ian Miller, scroll down to the bottom, and enter 555777 for the registration ID.

7. Click Save.

8. From the Global Menu, navigate to Applications → Blueprints.

9. Click Add () to begin creating a search blueprint.

10. For title, enter RegistrationId and click Create.

11. In the right menu of query elements, expand the FILTER section, find the Filter by Exact Terms Match element, and click Add for the element.

12. Enter these values:

    Field	Value
    Field	expando__keyword__custom_fields__RegistrationId_long
    Values	${keywords}

    

13. Click Save and take note of ID number of the search blueprint (e.g. 32256).

14. In the Global Menu, navigate to Control Panel → Instance Settings.

15. Click Feature Flags and go to Beta in the left navigation.

16. Scroll down and enable Search Headless API (LPS-179669).

    Note: Beta features are not recommended for production use, but this feature will be available as a full feature Q3 2024.

17. Use a new browser window and access Liferay’s API Explorer at http://localhost:8080/o/api.

18. Click the REST Applications drop-down menu and select portal-search-rest/v1.0.

19. Expand the postSearchPage endpoint panel and scroll down to the Request Body section.

20. From the downloaded course bundle, navigate to the [repository-folder]/exercises/lesson-18/ folder, then open the api-post-search.json file.

21. Copy the data from the file and paste it into the Request Body field.

22. Replace {blueprint ID} with the ID number of your search blueprint.

23. For nestedFields, enter embedded.

24. For search, enter 555777.

25. Click Execute.

26. Verify this returns Ian Miller’s user information.

    

    In this way, Liferay can be set up as a headless system that can be utilized by a third-party service.

You’ve used a custom registration ID field with search blueprints to retrieve user information.

Conclusion

Congratulations! You’ve completed Module 9 - Search. Throughout this module, you learned about working with the various tools and features Liferay Search offers.

In the next module, you’ll learn how you can use Liferay Objects to customize Liferay DXP.

Up Next: Module 10 - Customizing Liferay DXP

Additional Resources

See official documentation to learn more about using search blueprints to tailor search experiences:

• Search Blueprints
• Collections with Search Blueprints
• Adding Custom Fields