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.
Difference between revisions of "E4/Search Console/Developers Guide"
| Line 3: | Line 3: | ||
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 | 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 | ||
| − | [[Image: | + | [[Image:01 Search Console Overview.png|center]]<br><br> |
== Controller == | == Controller == | ||
| Line 11: | Line 11: | ||
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. | 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. | ||
| − | [[Image: | + | [[Image:02 Search Console Controller Sequence.png|center]]<br> |
<br> | <br> | ||
| Line 25: | Line 25: | ||
*the search providers implementations available | *the search providers implementations available | ||
| + | <br> | ||
| − | + | [[Image:03 Search Engine.png|center]] | |
| − | [[Image: | + | |
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. | 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. | ||
| Line 40: | Line 40: | ||
*to display the search result | *to display the search result | ||
| − | [[Image: | + | [[Image:04 Seach Console View.png|center]]<br> |
<br> Contributors are allowed to contribute their own UI (Custom Search Parameters) via which they can create user interface for displaying special custom search parameters. | <br> Contributors are allowed to contribute their own UI (Custom Search Parameters) via which they can create user interface for displaying special custom search parameters. | ||
| Line 56: | Line 56: | ||
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) | 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) | ||
| − | <br>[[Image: | + | <br>[[Image:05 Search Console Integration Layer.png|center]]<br> |
<br> The sequence diagram below gives some more details on installing the actions into the UI | <br> The sequence diagram below gives some more details on installing the actions into the UI | ||
| − | [[Image: | + | [[Image:06 Search Console - Installing Actions Sequence.png|center]]<br> |
| − | <br> | + | <br> |
= Search Favourites = | = Search Favourites = | ||
| Line 68: | Line 68: | ||
Search favourites is also built on top of the MVC design pattern | Search favourites is also built on top of the MVC design pattern | ||
| − | [[Image: | + | [[Image:07 Search Favourites MVC.png|center]]<br> |
The search favourites view can be customized the same way as the search console result view – via slave controllers and view customizations. | The search favourites view can be customized the same way as the search console result view – via slave controllers and view customizations. | ||
| Line 76: | Line 76: | ||
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 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 | ||
| − | <br> [[Image: | + | <br> [[Image:08 Search Favourites Persistency.png|center]] |
<br> The sequence diagram below illustrates the interaction between view, controller, persistency framework and store providers when an item is being “bookmarked” | <br> The sequence diagram below illustrates the interaction between view, controller, persistency framework and store providers when an item is being “bookmarked” | ||
| − | <br> [[Image: | + | <br> [[Image:09 Search Favourites Persistency Sequence.png|center]] |
<br> When the search favourites view is opened the bookmarked items are being loaded | <br> When the search favourites view is opened the bookmarked items are being loaded | ||
| − | <br>[[Image: | + | <br>[[Image:10 Search Favourites Loading Sequence.png|center]]<br> |
| − | <br> | + | <br> |
= Contributing to the search console = | = Contributing to the search console = | ||
| Line 95: | Line 95: | ||
== Object types == | == Object types == | ||
| + | |||
<source lang="xml"> | <source lang="xml"> | ||
<extension | <extension | ||
| Line 103: | Line 104: | ||
</objecttype> | </objecttype> | ||
</extension> | </extension> | ||
| − | </source> | + | </source> |
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 | 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 | ||
| Line 110: | Line 111: | ||
== Destination categories == | == Destination categories == | ||
| − | <source lang=xml> | + | |
| + | <source lang="xml"> | ||
<extension | <extension | ||
point="org.eclipse.platform.discovery.runtime.destinationcategory"> | point="org.eclipse.platform.discovery.runtime.destinationcategory"> | ||
| Line 119: | Line 121: | ||
</destinationcategory> | </destinationcategory> | ||
</extension> | </extension> | ||
| − | </source> | + | </source> |
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. | 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. | ||
| Line 126: | Line 128: | ||
== Search destinations providers == | == Search destinations providers == | ||
| − | <source lang=xml> | + | |
| + | <source lang="xml"> | ||
<extension | <extension | ||
point="org.eclipse.platform.discovery.runtime.destinationsprovider"> | point="org.eclipse.platform.discovery.runtime.destinationsprovider"> | ||
| Line 135: | Line 138: | ||
</destinationsprovider> | </destinationsprovider> | ||
</extension> | </extension> | ||
| − | </source> | + | </source> |
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 | 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 | ||
| Line 145: | Line 148: | ||
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 | 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 | ||
| − | <source lang=xml> | + | <source lang="xml"> |
<extension | <extension | ||
point="org.eclipse.platform.discovery.runtime.searchsubdestinations"> | point="org.eclipse.platform.discovery.runtime.searchsubdestinations"> | ||
| Line 159: | Line 162: | ||
</subdestination> | </subdestination> | ||
</extension> | </extension> | ||
| − | </source> | + | </source> |
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 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. | ||
| Line 168: | Line 171: | ||
== Search providers == | == Search providers == | ||
| − | <source lang=xml> | + | |
| + | <source lang="xml"> | ||
<extension | <extension | ||
point="org.eclipse.platform.discovery.runtime.searchprovider"> | point="org.eclipse.platform.discovery.runtime.searchprovider"> | ||
| Line 181: | Line 185: | ||
</searchprovider> | </searchprovider> | ||
</extension> | </extension> | ||
| − | </source> | + | </source> |
<br> 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. | <br> 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. | ||
| Line 189: | Line 193: | ||
== Advanced parameters == | == Advanced 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. | + | 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. <source lang="xml"> |
| − | <source lang=xml> | + | |
<extension | <extension | ||
point="org.eclipse.platform.discovery.integration.customsearchparams"> | point="org.eclipse.platform.discovery.integration.customsearchparams"> | ||
| Line 199: | Line 202: | ||
</customsearchparams> | </customsearchparams> | ||
</extension> | </extension> | ||
| − | </source> | + | </source> |
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. | 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. | ||
| Line 207: | Line 210: | ||
== Custom search results user interface == | == Custom search results user interface == | ||
| − | Contributors may implement their own user interface which displays the search results | + | Contributors may implement their own user interface which displays the search results <source lang="xml"> |
| − | <source lang=xml> | + | |
<extension | <extension | ||
point="org.eclipse.platform.discovery.ui.customresultui"> | point="org.eclipse.platform.discovery.ui.customresultui"> | ||
| Line 217: | Line 219: | ||
</contributor> | </contributor> | ||
</extension> | </extension> | ||
| − | </source> | + | </source> |
<br> 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. | <br> 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. | ||
| Line 227: | Line 229: | ||
The search console offers a generic implementation for displaying the search results. Contributors may customize the generic view via search controllers and view customizations. This concept has been already discussed above. Therefore only their contribution is shown in the example below | The search console offers a generic implementation for displaying the search results. Contributors may customize the generic view via search controllers and view customizations. This concept has been already discussed above. Therefore only their contribution is shown in the example below | ||
| − | <source lang=xml> | + | <source lang="xml"> |
<extension | <extension | ||
point="org.eclipse.platform.discovery.integration.searchconsole"> | point="org.eclipse.platform.discovery.integration.searchconsole"> | ||
| Line 239: | Line 241: | ||
</slavecontroller> | </slavecontroller> | ||
</extension> | </extension> | ||
| − | </source> | + | </source> <br> |
| − | <br> | + | |
= Contributing to the search favourites = | = Contributing to the search favourites = | ||
| Line 249: | Line 250: | ||
*Store provider | *Store provider | ||
| − | <source lang=xml> | + | |
| + | <source lang="xml"> | ||
<extension | <extension | ||
point="org.eclipse.platform.discovery.integration.persistence.mementostoreprovider"> | point="org.eclipse.platform.discovery.integration.persistence.mementostoreprovider"> | ||
| Line 257: | Line 259: | ||
</provider> | </provider> | ||
</extension> | </extension> | ||
| − | </source> | + | </source> |
The “provider” element specifies the store provider. Its “class” attribute specifies the fully qualified name of the class which implements the provider | The “provider” element specifies the store provider. Its “class” attribute specifies the fully qualified name of the class which implements the provider | ||
| Line 264: | Line 266: | ||
*Load provider | *Load provider | ||
| − | <source lang=xml> | + | |
| + | <source lang="xml"> | ||
<extension | <extension | ||
point="org.eclipse.platform.discovery.integration.persistence.mementoloadprovider"> | point="org.eclipse.platform.discovery.integration.persistence.mementoloadprovider"> | ||
| Line 272: | Line 275: | ||
</provider> | </provider> | ||
</extension> | </extension> | ||
| − | </source> | + | </source> |
The “provider” element specifies the load provider. Its “class” attribute specifies the fully qualified name of the class which implements the provider | The “provider” element specifies the load provider. Its “class” attribute specifies the fully qualified name of the class which implements the provider | ||
| Line 280: | Line 283: | ||
== Customizing the search favourites view == | == 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 | + | 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 <source lang="xml"> |
| − | <source lang=xml> | + | |
<extension | <extension | ||
point="org.eclipse.platform.discovery.integration.searchfavorites"> | point="org.eclipse.platform.discovery.integration.searchfavorites"> | ||
| Line 293: | Line 295: | ||
</slavecontroller> | </slavecontroller> | ||
</extension> | </extension> | ||
| − | </source> | + | </source> |
<br> | <br> | ||
<br> | <br> | ||
Revision as of 09:09, 29 December 2012
Contents
Search Console Overview
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
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
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.
Advanced 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.integration.customsearchparams"> <customsearchparams id="org.eclipse.demo.cheatsheets.search.customsearchparams2" searchproviderid="org.eclipse.demo.cheatsheets.search.internal.search.LocalCheatSheetSearchProvider" uicontributorclass="org.eclipse.demo.cheatsheets.search.internal.CustomSearchParamsUiContributor"> </customsearchparams> </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.
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.
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 search 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>
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
- 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
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>