The DX Core Periscope Result Ranker module works with the periscope modules to provide neural network-based ranking for your search results.
Module structure
artifactID | Description |
---|---|
magnolia-periscope-parent
| Parent reactor. |
| Provides an API to plug in search result suppliers to the search result set, as well as to create your own query sniffers (for example for vocal commands). |
| Provides the default search result supplier and periscope operation configuration files. |
| Optional submodule. Provides the speech recognition module and service to enable voice data processing. |
Installing
Maven is the easiest way to install the modules. Add the following dependencies to your webapp. All the other necessary dependencies will be brought in automatically:
Configuration
There's no additional configuration required for standard use because the default configuration provides a number of search result suppliers and periscope operations. All content apps are detected upon startup and corresponding search result suppliers for their workspaces are generated by the system on-the-fly.
You may configure additional search result suppliers and periscope operations to suit your specific needs. For general usage information, see the Find Bar page.
Search result suppliers
Search result suppliers are responsible for providing results to the Find Bar.
By default, all the Magnolia JCR workspaces are searchable. Content apps are detected when you start Magnolia and the system generates corresponding
SearchResultSuppliers
for their workspaces automatically. For performance reasons, search results are limited by default to 10 items per search result supplier and 100 items in total.
For example, this is the definition for the Pages app:
class: info.magnolia.periscope.search.jcr.JcrSearchResultSupplierDefinition workspace: website nodeTypes: - mgnl:page fullTextSearch: true titleProperty: title icon: webpages-app
If you want to search non-JCR databases or external datasets, you must create your own corresponding SearchResultSupplier
.
For normal content apps you don't need to create your own SearchResultSupplier
Java class or YAML definition. Search result suppliers for existing JCR workspaces (at start up) are generated automatically.
Creating a custom search result supplier
Use the SearchResultSupplierDefinition interface provided by the magnolia-periscope-api
submodule to implement a search result supplier. For example, you could implement a search result supplier to search through images stored on S3 or Flickr.
public interface SearchResultSupplier { String getName(); Stream<SearchResult> search(SearchQuery query) throws SearchException; }
SearchResultSupplier
is responsible for supplying results. The results of suppliers are represented by SearchResult
objects which contain text, metadata and a periscope operation request, which specifies what should be done when a user selects that result.public class SearchResult { @Wither private final String title; @Wither private final String content; @Wither private final String path; private final OperationRequest operationRequest; private final String type; private final String lastModifiedBy; private final ZonedDateTime lastModified; }
For example, the built-in JcrSearchResultSupplierDefinition
creates an InternalNavigationRequest
to open the result selected by the user in Magnolia.
For REST integrations
You can define a search result supplier using YAML for integration of external data set through REST. For more details, see the page REST search result suppliers for Periscope.
For JCR workspaces
Content apps are detected when you start Magnolia and the system generates corresponding SearchResultSuppliers
for their JCR workspaces automatically. You only need to define a search result supplier using YAML to search JCR workspaces if you want to customize the supplier. Magnolia provides a registry with a specific JcrSearchResultSupplierDefinition class that searches over defined JCR workspaces using specific node types and with the option of performing full-text search.
In the example below, the JcrSearchResultSupplierDefinition
class, <my-custom-workspace>
workspace and node type <my-node-type>
are specified. Full-text search is activated within the workspace defined.
workspace: <my-custom-workspace> nodeTypes: - <my-node-type> fullTextSearch: true titleProperty: caption class: info.magnolia.periscope.search.jcr.JcrSearchResultSupplierDefinition
Properties
class | required Fully qualified class name of the definition. Must extend |
enabled | optional, default is When |
workspace | required Workspace to be searched. |
nodeTypes | required List of node types to be searched. |
titleProperty | required JCR property to be considered the title of a node. It is always searched and used for the result title. |
fullTextSearch | optional, default is When |
appName | optional Name of your app. Specifies which app is opened when a result is clicked. |
Disabling search result suppliers
To disable search result suppliers, use the suppliers
property. Alternatively, you can provide your own Find Bar configuration through component mapping. For example, you can add a custom configuration provider to your module descriptor:
<component> <type>info.magnolia.admincentral.findbar.FindBarConfigurationProvider</type> <implementation>com.example.findbar.CustomFindBarConfigurationProvider</implementation> </component>
Changing the order of supplier results
Results are presented asynchronously by search result suppliers, from all workspaces and in the following default order:
- Apps
- Pages
- Stories
- Assets
- Tours
- Any other search result suppliers in alphabetical order.
To change the order of supplier results, use the supplierOrder
property. Alternatively, you can provide your own Find Bar configuration through component mapping (see the example above).
Configuring the default number of search results per supplier
For performance reasons, search results are limited by default to 10 items per search result supplier.
To configure the default number of search results per supplier, use the defaultCountPerSupplier
property. Alternatively, you can provide your own Find Bar configuration through component mapping (see the example above).
Periscope operations
Periscope operations are actions that are executed based on a corresponding operation request, usually triggered by a search result when a user clicks it in the Find Bar.
By default, Magnolia provides the following Operations
out-of-the-box:
- Internal navigation – shows an item inside a workspace by opening the corresponding app.
- External navigation – opens a URL in a new browser tab.
- App navigation – opens an app.
Example: Operation
definition provided for opening an app when a user clicks the "pages app" result or types "open pages app":
requestClass: info.magnolia.periscope.operation.request.AppNavigationRequest operationClass: info.magnolia.admincentral.findbar.operation.AppNavigationOperation
Configuring an Operation
Developers can define additional custom operations to be used by result suppliers.
This is the generic interface that should be implemented in order to introduce a new Operation
:
public interface Operation<R> { OperationResult execute(R request); }
In order for Periscope to register the operation, create a definition complying with OperationDefinition
, for example by creating a YAML file under src/main/resources/<module-name>/operations
as follows. In this example, a MyCustomOperation
is executed whenever a SearchResult
's getOperationRequest()
returns an instance of MyCustomRequest
(after the result has been clicked).
requestClass: com.example.mypackage.MyCustomRequest operationClass: com.example.mypackage.MyCustomOperation
Operation definitions work like any other definition in Magnolia, meaning they support features like decorations or hot-swapping.
Query sniffers
Query sniffers are listeners for changes in the Find Bar. When a user enters a search query into the Find Bar (by typing or speaking), Periscope notifies all registered sniffers. The sniffers then decide whether to take action or not based on the same query.
All built-in query sniffers have the form of commands: they execute an action based on certain text patterns. The default ones are:
- Find – searches and opens the first result:
- node (node name or title), triggered by queries like "find mountain tour".
- content (full-text), triggered by queries like "find pages about biking".
- Open – command to open apps, triggered by, for example, "open assets app".
Defining query sniffers
Custom query sniffers can be introduced by implementing the QuerySniffer
interface:
public interface QuerySniffer { Optional<OperationResult> sniff(String query); }
For sniffers intended to take action based on a regex pattern, extend PatternCommandSniffer
, which abstracts away the matching part. For example, a command for creating contacts can be implemented as follows:
public abstract class CreateContactCommandSniffer extends PatternCommandSniffer { private static final Pattern COMMAND_PATTERN = Pattern.compile("create contact (?<contactName>([^\\s]+))"); @Override protected abstract Pattern getPattern() { COMMAND_PATTERN; } @Override protected abstract OperationResult execute(Matcher matcher) { String contactName = matcher.group("contactName"); // ... (create contact) return new OperationResult(true, "Successfully created new contact named: " + contactName); } }
To be recognized by Periscope, each sniffer must be registered through a definition. New query sniffer definitions are automatically detected by the running system. To register a sniffer, create a YAML definition file under src/main/resources/<module-name>/querySniffers
as follows:
snifferClass: com.example.periscope.sniff.CreateContactCommandSniffer
Just like other definitions, sniffer definitions are listed in the Definitions app. If something is not working as expected, this is a good place to start troubleshooting.
Speech recognition service
The speech-recognition module provides the speech recognition service to enable voice data processing for users searching using the Find Bar. Typically users speak to Magnolia via a microphone and the speech recognition service translates their voice data into text. The periscope executes that text like a normal text query from the user.
The default Speech recognition implementation uses Web Speech API.
Check which browsers are supported by the Web Speech API here. At the time of publication, only Google Chrome was supported.