Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
E4/Search Console/Developers Guide
The search console is a highly extensible framework which allows contributing capabilities of searching and consuming of any kind of artefacts. The framework offers a common user interface for entering search query parameters, displaying the query results and bookmarking useful result items. The search console is domain-agnostic to the discovered artefacts and therefore does not impose domain related restrictions Contributors are only required to implement their business logic specific to objects discovery and their consumption.
Contents
Search Console
The Search Console is implemented on top of the Model-View-Controller design pattern. The diagram below shows the Search Console main components and the relationship between them
Controller
The controller is an internal component and cannot be used directly from contributors. The controller implements use-cases and determines the framework state at every point in time. The controller interacts with outer world via the view. In the case of the search console the view is represented by a small UI framework which on its turn can be customized. To put in in other way, the controller's purpose is to gather the user input data, to pass it to the search engine, to receive the search result and make the UI display it.
Search Engine
The search engine has the purpose of identifying
- the registered object types
- the search destination categories available
- the search providers implementations available
When the search starts, the search engine chooses suitable for the currently selected search destination and object type search provider and executes its search query. The result from the search query is passed back to the controller.
View
The view has two main responsibilities:
- to gather the input parameters
- to display the search result
Contributors are allowed to contribute their own UI (Custom Search Parameters) via which they can create user interface for displaying special custom search parameters.
There are two options for displaying the search result
- Contributors may register their own UI. The search result will be passed to this UI and it is up to its implementation to represent it in the desired way. With this approach however, contributors are on their own and it is up to them to integrate the results within the Eclipse environment (drag and drop, context menus, etc.)
- Search console provides a generic results UI which look and feel can be customized. The result is displayed in a tree structure. Contributors can:
- build the tree structure (via content providers)
- customize the tree nodes' looks (via label providers)
- build the tree nodes' tool tip content (via tool tip providers)
- register double click listeners
- create context menu items/toolbar buttons to work with the search result
In order to customize the generic results UI, contributors should register slave controllers and view customizations via the designated extension points. Slave controllers should contribute actions which represent the business logic for the operations to be performed on search result items. View customizations are supposed to install these contributed actions into the user interface (via e.g. context menu, toolbar buttons)
The sequence diagram below gives some more details on installing the actions into the UI
Search Favourites
The search favourites component implements "bookmarking" an already discovered item for further use. Bookmarks are physically persisted and can survive a workbench restart.
Search favourites is also built on top of the MVC design pattern
The search favourites view can be customized the same way as the search console result view – via slave controllers and view customizations.
Persistency
The favourite items persistency is implemented via a persistency framework. Contributors which would like to take advantage of persisting favourite items should contribute store providers and load providers
The sequence diagram below illustrates the interaction between view, controller, persistency framework and store providers when an item is being “bookmarked”
When the search favourites view is opened the bookmarked items are being loaded
Contributing to the search console
The search console defines several several extension points via which contributors may contribute implementations to the framework.
Object types
<extension point="org.eclipse.platform.discovery.runtime.objecttype"> <objecttype displayname="Cheat Sheets" id="org.eclipse.demo.cheatsheets.search.objecttype.cheatSheet"> </objecttype> </extension>
The registered object types appear in the “search for” combobox. The value of the “displayname” attribute is displayed to the user, and the value of the “id” attribute is used as unique object type identifier
Destination categories
<extension point="org.eclipse.platform.discovery.runtime.destinationcategory"> <destinationcategory destinationclass="org.eclipse.demo.cheatsheets.search.destinations.CSDestination" displayname="Local Cheetsheets" id="org.eclipse.demo.cheatsheets.search.destinationcategory.local"> </destinationcategory> </extension>
A destination category groups similar search destinations. The “displayname” attribute value is used for displaying purposes. The value of the “id” attribute represents unique destination category identifier. The value of the “destinationclass” attribute specifies the class/interface which all search destinations from this group should extend/implement. Check the search destinations provider extension point for details on this attribute.
Search destinations providers
<extension point="org.eclipse.platform.discovery.runtime.destinationsprovider"> <destinationsprovider destcategoryid="org.eclipse.demo.cheatsheets.search.destinationcategory.local" id="org.eclipse.demo.cheatsheets.search.destinationsprovider.local" provider="org.eclipse.demo.cheatsheets.search.destinations.LocalCSDestinationsProvider"> </destinationsprovider> </extension>
A destination provider is an implementation which providers available search destinations for a destination category specified (attribute “destcategoryid”). There might be several destinations providers per a single destination category. However, all the destinations they provide should extend/implement the class/interface specified by the “destinationclass” attribute of the destination category contribution.
Destinations providers contributors may optionally specify a preference page ID which configures the destinations provided by this provider via the preferencepageid extension point attribute. The preference page will be available in the filtered preference page dialog started when clicking the Manage Destinations hyperlink in the parameters section of the search console. However, in order to ensure consistent user experience, contributors are encouraged to contribute destinations preferences configurators
Destinations providers are required to implement the IDestinationsProvider interface
Search subdestinations
It is possible to specify that the keyword we are searching for is located in a specific “attribute” of the search artefact. For example, one may want to search for a keyword in an artefact's documentation or in the artefact technical name. In order to implement this feature the search console introduces search subdestinations
<extension point="org.eclipse.platform.discovery.runtime.searchsubdestinations"> <subdestination id="org.eclipse.demo.cheatsheets.search.subdestination.name" displayname="Name" objecttypeid="org.eclipse.demo.cheatsheets.search.objecttype.cheatSheet" categoryid="org.eclipse.demo.cheatsheets.search.destinationcategory.local" defaultSelected="true"> <conflict conflictingSubdID="org.eclipse.demo.cheatsheets.search.subdestination.description"> </conflict> </subdestination> </extension>
The subdestination contribution should specify the object type ID it is relevant for. The “defaultSelected” attribute specifies whether the subdestination should be enabled by default. The “conflict” element specifies a list of subdestination Ids which this subdestinations conflicts with. Thus it is possible to define mutual subdestinations.
The subdestinations (if available) appear in a drop-down box available right next to the keyword textbox.
Search providers
<extension point="org.eclipse.platform.discovery.runtime.searchprovider"> <searchprovider id="org.eclipse.demo.cheatsheets.search.internal.search.LocalCheatSheetSearchProvider" instance="org.eclipse.demo.cheatsheets.search.internal.search.LocalCheatSheetSearchProvider" objecttypeid="org.eclipse.demo.cheatsheets.search.objecttype.cheatSheet" supportstextsearch="true"> <category categoryid="org.eclipse.demo.cheatsheets.search.destinationcategory.local"> </category> </searchprovider> </extension>
The value of the “instance” attribute specifies the fully qualified name of the class implementing the search provider. The value of the “objecttypeid” attribute specifies the object type this search provider is capable of searching for. The boolean value of the “supportstextsearch” attribute specifies whether the current search provider can search by a keyword. The “category” element specifies a list IDs of destination categories this search provider is applicable for.
Search providers instances are required to implement the ISearchProvider interface
Advanced search parameters
It is very possible that the standard search parameters (destination and keyword) are not sufficient for performing a search. Therefore contributors may specify their custom UI via which the user can input additional search constraints. This UI is displayed in an “advanced options” section in the search console view.<extension point="org.eclipse.platform.discovery.ui.advancedsearchparams"> <advancedsearchparams id="org.eclipse.demo.cheatsheets.search.advancedsearchparams" searchproviderid="org.eclipse.demo.cheatsheets.search.internal.search.LocalCheatSheetSearchProvider" uicontributorclass="org.eclipse.demo.cheatsheets.search.internal.CustomSearchParamsUiContributor"> </advancedsearchparams> </extension>
The value of the “uicontributorclass” specifies the fully qualified name of the class which implements the custom user interface. The value of the “searchproviderid” attribute specified the ID of the search provider this user interface is applicable for.
UI contributor instances are required to implement the IAdvancedSearchParamsUiContributor interface
Custom search results user interface
Contributors may implement their own user interface which displays the search results<extension point="org.eclipse.platform.discovery.ui.customresultui"> <contributor id="org.eclipse.demo.cheatsheets.search.resultui.creator" creator="org.eclipse.demo.cheatsheets.search.internal.resultui.SearchResultCustomUiCreator" searchproviderid="org.eclipse.demo.cheatsheets.search.internal.search.LocalCheatSheetSearchProvider"> </contributor> </extension>
The value of the “creator” attribute specifies the fully qualified name of the class which creates the custom UI. The value of the “searchproviderid” specifies the ID of the search provider whose result should be displayed by this custom UI.
The results UI creators instances are required to implement the ISearchResultCustomUiCreator interface
Customizing the generic search result user interface
The search console offers a generic implementation for displaying the search results. Contributors may customize the generic view via slave controllers and view customizations. This concept has been already discussed above. Therefore only their contribution is shown in the example below
<extension point="org.eclipse.platform.discovery.integration.searchconsole"> <viewcustomization customizationimpl="org.eclipse.demo.cheatsheets.search.internal.view.console.ConsoleCustomization" id="org.eclipse.demo.cheatsheets.search.internal.view.ConsoleCustomization"> </viewcustomization> <slavecontroller id="org.eclipse.demo.cheatsheets.search.internal.slave.ConsoleSlaveController" implclass="org.eclipse.demo.cheatsheets.search.internal.slave.ConsoleSlaveController"> </slavecontroller> </extension>
Slave controllers are required to implement the ISearchConsoleSlaveController interface; view customizations are required to implement the ISearchConsoleCustomization interface
Contributing to the search favourites
Persistency
Favourites items are stored and loaded via implementation called store and load providers. This concept has been already discussed above. Below are examples for contributing such implementations
- Store provider
<extension point="org.eclipse.platform.discovery.integration.persistence.mementostoreprovider"> <provider class="org.eclipse.demo.cheatsheets.search.internal.persistency.CSStoreProvider" id="org.eclipse.demo.cheatsheets.search.internal.persistency.CSStoreProvider"> </provider> </extension>
The “provider” element specifies the store provider. Its “class” attribute specifies the fully qualified name of the class which implements the provider
Store providers are required to implement the IMementoStoreProvider interface
- Load provider
<extension point="org.eclipse.platform.discovery.integration.persistence.mementoloadprovider"> <provider class="org.eclipse.demo.cheatsheets.search.internal.persistency.CSLoadProvider" id="org.eclipse.demo.cheatsheets.search.internal.persistency.CSLoadProvider"> </provider> </extension>
The “provider” element specifies the load provider. Its “class” attribute specifies the fully qualified name of the class which implements the provider
Load providers are required to implement the IMementoLoadProvider interface
Customizing the search favourites view
Similarly to search console customization, contributors may register slave controllers and view customizations to the search favourites view. The concept has been already discussed so here is just an example<extension point="org.eclipse.platform.discovery.integration.searchfavorites"> <viewcustomization customizationimpl="org.eclipse.demo.cheatsheets.search.internal.view.favorites.FavoritesCustomization" id="org.eclipse.demo.cheatsheets.search.internal.view.favorites.FavoritesCustomization"> </viewcustomization> <slavecontroller id="org.eclipse.demo.cheatsheets.search.internal.slave.FavoritesSlaveController" implclass="org.eclipse.demo.cheatsheets.search.internal.slave.FavoritesSlaveController"> </slavecontroller> </extension>
Slave controllers are required to implement the ISearchFavoritesSlaveController interface; view customizations are required to implement the ISearchFavoritesViewCustomization interface
Search destinations preferences
Search destinations are the concrete places a search can be performed in. In the most common case, those destinations provide information on how to connect to a remote system. In order to provide consistent user experience, the search console framework offers the Search Destinations preference page which is designed to create new search destinations and manage existing ones.
Search components could contribute a destinations configurator in order to plug into this preference page<extension point="org.eclipse.platform.discovery.destprefs.configurator"> <destinationConfigurator contributorClass="org.eclipse.demo.cheatsheets.ui.CheatSheetsDestinationPrefsConfigurator" destProviderId="org.eclipse.demo.cheatsheets.search.destinationsprovider.local" id="org.eclipse.demo.cheatsheets.ui.dest.prefs.configurator"> </destinationConfigurator> </extension>
The destProviderId attribute specifies the ID of the destinations provider which destinations this configurator operates on. The contributorClass attribute specified the fully qualified name of the configurator implementation
Contributed preferences configurators are required to implement the ISearchDestinationConfigurator interface