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 Global Menu (), go to the Applications tab, and click Asset Libraries.

3. Select the HR library and click Web Content.

4. Go to the Structures tab and begin editing Job Listing.

5. Click Properties () and copy down the Structure Key value.

6. Open the Global Menu (), go to the Applications tab, and click Blueprints.

7. Click Add ().

8. For Title, enter Job Listings Last 60 Days.

9. Click Create.

10. In the right side menu, search for Filter by Exact Terms Match and click Add to include it in your query.

11. For Field, enter ddmStructureKey.

12. For Values, enter the Job Listing Structure Key.

    

13. In the left navigation, click Query Settings.

14. Click Selected Types and click Select Asset Types.

15. Select Web Content Article and click Done.

16. In the top menu, click Preview and enter a job listing search (e.g., Developer).

17. In the left navigation, click Query Elements.

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

19. In the right side menu, search for Custom JSON Element and click Add for the element.

20. Delete the Custom JSON Element’s sample JSON.

21. From the training workspace, open the filter-last-60d.json file in the [repository-folder]/exercises/lesson-18/ folder.

22. Copy the contents of filter-last-60d.json into the Custom JSON Element.

    

23. Click Preview and click Refresh to see the filter applied.

24. In the Custom JSON Element, change "now-60d" to "now-1d" and click Refresh in the search preview to see the filter applied.

25. Change the value back to "now-60d".

26. Click Save.

    Next, you’ll update the Open Positions page to use the search blueprint.

27. Go to the Open Positions page and click Edit ().

28. From the Fragments and Widgets panel, drag and drop a Blueprints Options widget below the Search Options widget in the Search Results and Options container.

29. Click the Actions menu () and select Configuration.

30. For Blueprint, click Select and select the Job Listings Last 60 Days blueprint.

31. Click Save and close the window.

    With the blueprint applied, you can now remove the Type Facet and Custom Filter widgets from the page.

32. Click Publish.

    Now the search results only include job listings created in the last 60 days.

Great! You’ve created a search blueprint and applied it to the Open Positions page as an alternative to the Type Facet and Custom Filter widgets.

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 fragment to site pages.

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.

Here you’ll implement this as Clarity Admin.

Creating a Calendar Page

1. Open the Site Menu (), expand Site Builder, and click Pages.

2. Click New and select Page.

3. Select Primary Master Page.

4. For Name, enter Calendar.

5. Click Add.

6. In the Fragments and Widgets side panel, go to the Widgets tab.

7. Drag and drop the Calendar widget into the page.

8. Click Publish.

   Now that you’ve created the page, add some events to the calendar.

9. In the list of site pages, click Actions () for the Calendar page and select View.

10. Select the Month view and click any date before your current date, enter Past Event 1 as the name, and click Save.

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

12. Add one more event after Future Event 1 that is named Future Event 2.

    

With the page and events set up, you can set up a search blueprint. But before you do that, enable the feature flag for the blueprint integration with collections element for future events.

Enabling the Blueprint and Collections Integration

1. Open the Global Menu (), go to the Control Panel tab, and click Instance Settings.

2. Click Feature Flags and go to the Beta tab

3. Enable Collections with Search Blueprints (LPS-129412).

   Important: Beta features should not be used in production environments.

With this feature enabled, you can create a search blueprint element for future calendar events.

Creating a Future Events Search Blueprint Element

1. Open the Global Menu (), go to the Applications, and click Blueprints.

2. Go to the Elements tab and click Add.

3. For Title, enter Future Events

4. Click Create.

5. Delete the default JSON content.

6. From the training workspace, open the filter-future-events.json file in the [repository-folder]/exercises/lesson-18/ folder.

7. Copy the contents of filter-future-events.json into the JSON field.

8. Click Save.

Now you can create a blueprint that uses this element to query future events.

Creating a Future Events Search Blueprint

1. While in the Blueprints application, go to the Blueprints tab.

2. Click Add ().

3. For Title, enter Future Events

4. Click Create.

5. In the right side menu, search for Future Events and click Add to include it in your query.

6. In the left navigation, click Query Settings.

7. Click Selected Types and click Select Asset Types.

   

8. Select Calendar Event.

9. Click Done.

10. Click Save.

With the blueprint defined, you can now use its collection provider in a site page to render future events.

Using the Blueprint Collection Provider

1. Go to the Calendar page.

2. From the Fragments and Widgets panel, drag and drop a Container fragment above the below the Calendar widget.

3. Select the container and configure these settings in the configuration side panel:

   Tab	Setting	Value
   General	Content Display	Flex Column
   General	Align Items	Center
   General	Justify Content	Center
   Styles	Spacing > Padding	Spacer 6 (top and bottom)

4. From the Fragments and Widgets panel, drag and drop a Heading fragment into the container.

5. Set the Heading fragment’s text to Upcoming Events.

6. From the Fragments and Widgets panel, drag and drop a Collection Display fragment into the container below the Heading.

7. Select the Collection Display.

8. In the configuration side panel, click Select Collection ().

9. Go to the Collection Providers tab and select Future Events.

10. Configure these settings:

    Tab	Setting	Value
    General	Style Display	Bulleted List
    General	Pagination	None

11. Click Publish.

    

    The search blueprint automatically provides a collection of future events that’s rendered by the collection display.

You’ve now 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 those fields using headless APIs.

Exercise: Search Blueprints with Custom Fields

Occasionally businesses need to integrate with other web services. For example, Clarity wants their employee benefits system to reference their employees based on the service’s registration ID numbers. In Liferay, you can add custom fields to user accounts for this value. Then you can use Liferay’s headless APIs to query the custom field.

User Account APIs cannot filter for custom fields directly, but you can use search blueprints for this purpose. Here you’ll implement this as Clarity Admin.

To do this,

1. Open the Global Menu (), go to the Control Panel tab, and click Custom Fields.

2. Select User and click New.

3. Select Input Field and enter these details.

   Field	Value
   Field Name	RegistrationId
   Data Type	Integer

4. Click Save.

5. Open the Global Menu (), go to the Control Panel tab, and click Users & Organizations.

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

7. Click Save.

8. Open the Global Menu (), go to the Applications tab, and click Blueprints.

9. Click Add ().

10. For Title, enter Registration ID.

11. Click Create.

12. In the right side menu, search for Filter by Exact Terms Match and click Add to include it in your query.

13. For Field, enter expando__keyword__custom_fields__RegistrationId_long.

14. For Values, enter ${keywords}.

    

15. Click Save and copy down the blueprint’s ID.

16. Open the Global Menu (), go to the Control Panel tab, and click Instance Settings.

17. Click Feature Flags and go to the Beta tab.

18. Enable Search Headless API (LPS-179669).

    Important: Beta features should not be used in production environments, but this feature will be available as a full feature Q3 2024.

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

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

21. Expand the postSearchPage endpoint.

22. For nestedFields, enter embedded.

23. For search, enter 555777.

24. For Request Body, delete the default JSON content.

25. From the training workspace, open the api-post-search.json file in the [repository-folder]/exercises/lesson-18/ folder.

26. Copy the contents of api-post-search.json into the Request Body field.

27. Replace {blueprint ID} with your blueprint’s ID.

28. Click Execute.

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

    

    This is one way you can use Liferay as a headless system that’s 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