REST search result suppliers for Periscope

Search result suppliers are responsible for providing search results to the Find Bar’s search result area through the Periscope, its back-end. Below, we describe how you can configure and use search result suppliers that integrate search results of external content through REST.

This feature is only available in the DX Core edition of Magnolia.

For information about the Magnolia supplier that searches over defined JCR workspaces or about creating a custom search result supplier, see Periscope module: Creating a custom search result supplier.

Configuration properties

The REST-based supplier functionality for the Periscope module is provided by the magnolia-rest-client-ui module as a combination of the following specific Magnolia classes:

info.magnolia.rest.ui.periscope.RestClientResultSupplierDefinition
info.magnolia.rest.ui.periscope.SearchResultExpressionDefinition

A REST-based search result supplier can be created as a YAML file and configured using the following properties:

Property Description

Property	Description
`class`	required `info.magnolia.rest.ui.periscope.RestClientResultSupplierDefinition`
`restClient`	required Name of a configured REST client to fetch search data with.
`restCall`	required Name of a configured REST call definition in the client.
`searchResultExpression`	required List of JSON path expressions to get data for each item to be shown in the Find Bar search results area. Provided by the `info.magnolia.rest.ui.periscope.SearchResultExpressionDefinition` class.
`title`	required Expression to get the title of the item, for example: `$.values[*].title`
`url`	required Expression to get the URL address of the item, for example: `$.values[*].links.html.href`
`content`	optional Expression to show the detail of the item.
`editor`	optional Expression to get the editor name of the item.
`date`	optional Expression to get the last-modified date of the item. YAML files with configuration of search result suppliers should be stored in the `searchResultSuppliers` folder of your module: `<module-name> ├── apps ├── contentTypes ├── decorations ├── i18n ├── module.yaml ├── restClients │ └── <rest-client-name>.yaml ├── restEndpoints ├── searchResultSuppliers │ └── <search-result-supplier-name>.yaml └── templates`

class

required

info.magnolia.rest.ui.periscope.RestClientResultSupplierDefinition

restClient

required

Name of a configured REST client to fetch search data with.

restCall

required

Name of a configured REST call definition in the client.

searchResultExpression

required

List of JSON path expressions to get data for each item to be shown in the Find Bar search results area.

Provided by the info.magnolia.rest.ui.periscope.SearchResultExpressionDefinition class.

title

required

Expression to get the title of the item, for example:

$.values[*].title

url

required

Expression to get the URL address of the item, for example:

$.values[*].links.html.href

content

optional

Expression to show the detail of the item.

editor

optional

Expression to get the editor name of the item.

date

optional

Expression to get the last-modified date of the item.

YAML files with configuration of search result suppliers should be stored in the searchResultSuppliers folder of your module:

<module-name>
├── apps
├── contentTypes
├── decorations
├── i18n
├── module.yaml
├── restClients
│ └── <rest-client-name>.yaml
├── restEndpoints
├── searchResultSuppliers
│ └── <search-result-supplier-name>.yaml
└── templates

Sample REST integration

The following configuration files illustrate how you can deliver search results from outside of Magnolia. When enabled, the supplier definition integrates the issues from the PyPy project on bitbucket.org. If you query the project’s issue titles, the search result area of the Find Bar will display the results.

Supplier definition

class: info.magnolia.rest.ui.periscope.RestClientResultSupplierDefinition
restClient: bitbucket
restCall: searchTitleIssues
searchResultExpression:
  title: $.values[*].title
  url: $.values[*].links.html.href
  content: $.values[*].content.raw
  date: $.values[*].updated_on
enabled: true

Client definition

baseUrl: https://api.bitbucket.org
restCalls:
  searchTitleIssues:
    method: get
    entityClass: com.fasterxml.jackson.databind.JsonNode
    path: /2.0/repositories/pypy/pypy/issues
    queryParameters:
      q: "title~\"{query}\""

If you then search for runinterp in the find Bar, you should get one result for issue #3151 on the PyPy project:

PyPy project result

REST search result suppliers for Periscope

Configuration properties

Sample REST integration

Location

Main doc sections