Customizing search results

Brightspot provides several APIs to customize the search results that appear in the search panel. For example, you can set the fields that appear in search results, add actions that can be performed on results, and suggest results based on custom logic. Also, for applicable content types, you can add thumbnail images in the search carousel in the content edit page.

SearchResultField

You can select which fields appear in the search results with the Fields list in the results section of the search panel. Brightspot populates the Select Fields widget with default fields.

Using the SearchResultField interface, you can add custom fields to the widget. For example, say that you want the author name to appear for articles listed in the search results. You can implement SearchResultField to return the Author field for Article objects retrieved in a query, similar to the following example.

showLineNumbers {4,9,14}

1
public class AuthorField implements SearchResultField {
2

3
   @Override
4
   public String getDisplayName() {
5
      return "Author";
6
   }
7

8
   @Override
9
   public boolean isSupported(ObjectType type) {
10
      return true;
11
   }
12

13
   @Override
14
   public String createDataCellText(Object item) {
15
      Article article = State.getInstance(item).getOriginalObject() instanceof Article
16
             ? ((Article) State.getInstance(item).getOriginalObject()) : null;
17

18
      if (article != null) {
19
         if (article.getAuthor() != null)
20
            return article.getAuthor().getName();
21
         else return ("No attribution");
22
      }
23
      return null;
24
   }
25
}

• 4. Specifies how the field label appears in the search results.
• 9. Determines if the field appears in the search results. If the method returns false, the Author field does not appear in the Select Fields widget.
• 14. Filters for Article objects and returns null if the search result is not an Article. For objects where the Author field is set, the author name is returned; otherwise "No attribution" is returned.

With the new implementation, the Author field is now available in the Select Fields widget.

With a query on articles, the Author field is included in the search results.

SearchResultView

The SearchResultView interface allows you to customize the results section of the search panel. Brightspot includes default implementations, such as the list result view shown below. You can modify these implementations or create your own.

SearchResultAction

The search panel includes a widget for invoking operations on search results. The available actions that appear in the list can vary, depending on the content type filter setting.

Brightspot provides default action implementations as reflected in the above screen shot. You can also create custom actions by implementing the SearchResultAction interface and a page servlet that operates on search results. Brightspot automatically detects new action implementations.

To implement SearchResultAction, override the following methods:

• getGroup sets a group name in the UI for a set of related action implementations, like Bulk.
• getPosition sets the top-down position of the action in the UI list of actions. Implementations with the same position settings are arranged in alphabetical order based on the class name.
• shouldDisplay shows or hides the action in the UI.
• writeHtml constructs the HTML link that invokes the action when the button is clicked in the UI. The link references the path of the page servlet that processes the search results.

The following snippet shows the writeHtml implementation for the SaveSearchResultAction, which saves the search for the current result set. The method takes ToolPageContext, Search, and SearchResultSelection objects. The ToolPageContext object constructs the HTML link to the action servlet.

showLineNumbers {12,14}

1
@Override
2
 public void writeHtml(
3
         ToolPageContext page,
4
         Search search,
5
         SearchResultSelection selection)
6
         throws IOException {
7

8
   page.writeStart("div", "class", "searchResult-action-simple");
9
       page.writeStart("a",
10
               "class", "button",
11
               "target", "toolUserSaveSearch",
12
               "href", page.cmsUrl("/toolUserSaveSearch",
13
                       "search", page.url("", Search.NAME_PARAMETER, null)));
14
           page.writeHtml(page.localize(SaveSearchResultAction.class, "action.saveSearch"));
15
       page.writeEnd();
16
   page.writeEnd();
17
 }

• 12. Construct the URL to the page servlet, specified in the servlet routing path as toolUserSaveSearch. This page servlet is located in <project>src/main/java/com/psddev/cms/tool/page.
• 14. Specifies the label on the action button. If Brightspot is localized, you can pass a resource key to retrieve the label for the applicable UI language. For the search result APIs in the Brightspot project, place resource files in <project>src/main/resource/com/psddev/cms/tool/search.

SearchResultSelectionGeneratable

Leveraging the SearchResultSelectionGeneratable annotation, you can create a complex Content type with a search result action. For example, you can have a MultiMediaGallery type that consists of Image and Video slides. A query for Image or Video types displays an associated action in the search panel. Invoking the action creates a MultiMediaGallery object with any Image or Video objects selected in the search results.

The following steps show how to construct a search result action that creates a MultiMediaGallery content type.

Step 1: Create the content type

showLineNumbers {1,4,9,11,23,35}

1
@SearchResultSelectionGeneratable.ItemTypes({Image.class, Video.class})
2
public class MultiMediaGallery extends Content {
3

4
   private List<Slide> slides;
5
   public List<Slide> getSlides() { return slides; }
6
   public void setSlides(List<Slide> slides) { this.slides = slides; }
7

8
   @Embedded
9
   private static abstract class Slide extends Record { }
10

11
   private static class ImageSlide extends Slide {
12
      private Image image;
13

14
      public Image getImage() {
15
         return image;
16
      }
17

18
      public void setImage(Image image) {
19
         this.image = image;
20
      }
21
   }
22

23
   private static class VideoSlide extends Slide {
24
      private Video video;
25

26
      public Video getVideo() {
27
         return video;
28
      }
29

30
      public void setVideo(Video video) {
31
         this.video = video;
32
      }
33
   }
34

35
   public void fromSelection(SearchResultSelection selection) {
36

37
      for (Object object : selection.createItemsQuery().selectAll()) {
38
         if (object instanceof Image) {
39
             // If the selected object is an Image, create a new ImageSlide to wrap it.
40
             ImageSlide imageSlide = new ImageSlide();
41
             imageSlide.setImage((Image) object);
42
             getSlides().add(imageSlide);
43

44
         } else if (object instanceof Video) {
45
             // If the selected object is a Video, create a new VideoSlide to wrap it.
46
             VideoSlide videoSlide = new VideoSlide();
47
             videoSlide.setVideo((Video) object);
48
             getSlides().add(videoSlide);
49
         }
50
         // Ignore any other objects that are not Images or Videos
51
      }
52
   }
53
}

• 1. Class annotation that enables MultiMediaGallery objects to be created from Image and Video objects returned in search results.
• 4. Defines a list for a Slide type and associated getter and setter methods.
• 9. Embeds an abstract Slide class.
• 11. Implements an ImageSlide inner class for slides consisting of Image objects.
• 23. Implements a VideoSlide inner class for slides consisting of Video objects.
• 35. Implements the fromSelection method from the SearchResultSelectionGeneratable interface. The method creates Image or Video slides from the SearchResultSelectionObject. After usage of the SearchResultSelection to create a new Content instance, the SearchResultSelection is destroyed.

Step 2: Implement SearchResultAction

The SearchResultAction implementation displays the applicable action button in the search panel.

showLineNumbers {20,29,32}

1
public class MultiMediaGalleryAction implements SearchResultAction {
2

3
   @Override
4
   public int getPosition() {
5
      return 0;
6
   }
7

8
   @Override
9
   public boolean shouldDisplay(ToolPageContext page, Search search, SearchResultSelection selection) {
10
      return true;
11
   }
12

13
   // @Override
14
   public void writeHtml(
15
      ToolPageContext page,
16
      Search search,
17
      SearchResultSelection selection)
18
      throws IOException {
19

20
      if (selection == null) {
21
         return;
22
      }
23

24
      page.writeStart("div", "class", "searchResult-action-simple");
25

26
      page.writeStart("a",
27
             "class", "button",
28
             "target", "toolUserMultiMedia",
29
             "href", new UrlBuilder(page.getRequest())
30
                     .absolutePath(page.toolPath(CmsTool.class, "toolUserMultiMedia"))
31
                     .parameter("selectionId", selection.getId()));
32
      page.writeHtml(page.localize(MultiMediaGalleryAction.class, "action.MultiMediaGalleryAction"));
33
      page.writeEnd();
34
      page.writeEnd();
35
   }
36
}

• 20. Checks for search results that are selected in the UI. If there are no selections, then the implementation does not display the action button.
• 29. Constructs the URL to the page servlet, specified in the servlet routing path as tooUserMultiMedia. Only one parameter is passed to the servlet, selectionId, returned by the SearchResultSelection#getId() method.
• 32. Specifies the label on the action button. The label is retrieved from a localization resource file.

When results are selected in the search panel, the Create MultiMediaGallery button appears.

Step 3: Implement page servlet

The page servlet invoked from the search result action creates the MultiMediaGallery objects from the search result selections.

showLineNumbers {1,11,12,14}

1
@RoutingFilter.Path(application = "cms", value = "toolUserMultiMedia") public class ToolUserMultiMedia extends PageServlet {
2

3
   @Override
4
   protected String getPermissionId() {
5
      return null;
6
   }
7

8
   @Override
9
   protected void doService(ToolPageContext page) throws IOException, ServletException {
10

11
      UUID selectionId = page.param(UUID.class, "selectionId");
12
      SearchResultSelection selection = Query.from(SearchResultSelection.class).where("_id = ?", selectionId).first();
13

14
      MultiMediaGallery gallery = new MultiMediaGallery();
15
      gallery.fromSelection(selection);
16
      gallery.save();
17
   }
18
}

• 1. Specifies the annotation @RoutingFilter.Pathof the servlet as toolUserMultiMedia.
• 11. Gets the value of the selectionId parameter passed from MultiMediaGalleryAction.
• 12. Performs a query to get the SearchResultSelection object identified by selectionId.
• 14. Creates a MultiMediaGallery object. The SearchResultSelection object can represent selections of various content types. However, MultiMediaGallery is limited to Image and Video item types, so the implemented fromSelection method creates gallery slides from only those types.

SearchResultSuggester

When you click a selection field in the content edit form, the content picker appears with a list of search results applicable to the object type. For example, if an Article contains fields for Author and Image, clicking either of those fields invokes the Content Picker with a list of Author or Image search results. Obviously you want to select a result appropriate to the context of the containing article.

To assist the user in selecting a search result that’s most appropriate to the containing object type, you can implement suggestions to appear in the Content Picker search results. Say that you have an Article subclass for environmental content, which contains an Image field. To guide writers to set applicable images for the content type, you can implement filtering of search results and display suggestions for environmentally-themed images. In the following screen shot, Brightspot suggests images that are related to the environment.

How suggestions work

As search results are rendered in the content picker, the search renderer calls the page servlet SearchResultSuggestions. This servlet passes control to a SearchResultSuggester implementation with the highest priority. Based on the object on which the content picker was invoked (such as Article), and on the search results returned (such as Images), the SearchResultSuggester implementation determines if there are suggestions to offer. If so, the implementation passes the suggestions to the search renderer.

Brightspot includes a default SearchResultSuggester implementation, SolrSearchResultSuggester. This implementation uses Solr database scoring to check for suggestions.

Implementing SearchResultSuggester

Override the following methods:

• getPriority returns a numerical priority level that SearchResultSuggestions needs to determine which SearchResultSuggester implementation to use. The default priority level set in the SearchResultSuggester interface is zero. To use a SearchResultSuggester implementation other than the default SolrSearchResultSuggester, return a value greater than zero. To no longer use a SearchResultSuggester implementation, return a value less than zero.
• writeHtml contains the logic for determining suggestions. To continue with the above example, this method would evaluate the context of the Article object and the Image search results and pass suggestions, if any, to the search renderer.

Searching non-content objects

In Brightspot, non-content objects derive directly from Record and typically support Content-derived objects. For example, you can have a content-carrying Article class that references a Record-derived WriterContract class. This class represents the personal information of freelance writers who contribute articles.

showLineNumbers

1
public class WriterContract extends Record {
2

3
   @Indexed
4
   private String name;
5

6
   @Indexed
7
   private String address;
8

9
   private StorageItem contract;
10

11
   // getters and setters
12
}

Record-derived objects can only be searched by content type in the content picker, not in the search panel. In the content picker, only the first indexed field of a Record-derived object is searchable. All other indexed fields are ignored by default.

For example, if you click the Contract field in the content edit form for Article, the content picker shows all of the WriterContract objects. Because name is the first indexed field in the WriterContract class, you can only search on name in the content picker.

You can change Brightspot’s default search behavior for non-content objects in the following ways:

• Use the @Content.Searchable annotation, which makes all indexed fields of a Record-derived class searchable, from both the search panel and the content picker.
• Use the @Recordable.LabelFields annotation in conjunction with the @Indexed annotation.

All indexed fields listed in the @LabelFields annotation are full-text searchable in the content picker.

In the following example, the indexed fields of name and address are listed in the @LabelFieldsannotation, thereby making them both searchable.

showLineNumbers

1
@Recordable.LabelFields({"name", "address"})
2
public class WriterContract extends Record {
3

4
   @Indexed
5
   private String name;
6

7
   @Indexed
8
   private String address;
9

10
   private StorageItem contract;
11

12
   // getters and setters
13
}

In the content picker, you can now search on the address field as well as the name field to narrow the selection of WriterContract objects.