Periscope module
Operations Bundled: Community Edition
| Edition | CE |
|---|---|
License |
|
Issues |
|
Maven site |
|
Latest |
1.2.10 |
The Periscope module provides back-end functionality used by the Find Bar. It can be used out-of-the-box to search all content apps or extended by activating search in external data sources and by implementing operations commonly used by your users. The Find Bar brings the back-end search functionality of the Periscope module into the Magnolia UI. It provides the UI display of the Find Bar search box, search results grid and the drop-down filters to refine results.
Module structure
| artifactID | Description |
|---|---|
|
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. |
Installing with Maven
Bundled modules are automatically installed for you.
If the module is unbundled, add the following to your bundle including your project’s <dependencyManagement> section and your webapp’s <dependencies> section.
If the module is unbundled but the parent POM manages the version, add the following to your webapp’s <dependencies> section.
<dependency>
<groupId>info.magnolia.periscope</groupId>
<artifactId>magnolia-periscope-core</artifactId>
<version>1.2.10</version> (1)
</dependency>| 1 | Should you need to specify the module version, do it using <version>. |
<dependency>
<groupId>info.magnolia.periscope</groupId>
<artifactId>magnolia-speech-recognition</artifactId>
<version>1.2.10</version> (1)
</dependency>| 1 | Should you need to specify the module version, do it using <version>. |
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.
Asynchronicity of search queries
To improve search performance for multiple threads trying to get the same session on the same workspace, you neeed to change the limit of a total number of concurrent queries. Go to magnolia.properties file and adjust the magnolia.periscope.result.supplier.thread system property value.
Search result suppliers
Search result suppliers are responsible for providing results to the Find Bar.
|
By default:
|
For example, this is the definition for the Pages app:
class: info.magnolia.periscope.search.jcr.JcrSearchResultSupplierDefinition
appName: pages-app
workspace: website
nodeTypes:
- mgnl:page
fullTextSearch: true
titleProperty: title
icon: icon-webpages-app
order:
property: mgnl:lastModified
direction: DESCIf 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
For example, when the E-commerce app is installed, the respective
|
Creating a custom search result supplier
Use the
info.magnolia.periscope.search.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;
}Each 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
info.magnolia.periscope.search.jcr.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 <my-node-type> 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.JcrSearchResultSupplierDefinitionJcrSearchResultSupplierDefinition properties
| Property | Description |
|---|---|
|
required, default is Fully qualified class name of the supplier definition. Must implement the |
|
required Name of the workspace in
the |
|
required List of node types you want to search. If no value is specified, the supplier will search all node types. |
|
required Title of the searched node. Always searched by default and used as a title for the result. |
|
optional Name of the supplier. |
|
optional, default is Path configured as the root of the workspace. Only content below the path is operated on. |
|
optional, default is When |
|
optional, default is When |
|
optional, default is When |
|
optional, default is Limit on the total number of search results that can be retrieved. |
|
optional, default is Strategy used to construct a search result supplier from |
|
optional Node containing the order configuration of search results. See the info.magnolia.periscope.search.jcr.JcrSearchResultSupplierOrder class. |
|
required Node type property to sort search results by. Use a Magnolia node type or define your own property. |
|
required Sort direction for the node type property. Possible values are |
|
optional Name of the app that opens when a search result is clicked. |
|
optional Name of the subapp that opens when a search result is clicked. |
|
optional CSS class that identifies an icon used for the supplier. |
|
optional Text displayed on the supplier icon. The value is i18n-able. |
Disabling search result suppliers
To disable search result suppliers, modify 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 in main/resources/admincentral/config.yaml.
findBar:
suggestionCountPerSupplier: 3
defaultCountPerSupplier: 10
minimumSearchLength: 3Alternatively, 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.AppNavigationOperationConfiguring 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. |