Revision as of 06:31, 29 December 2012

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

[[Image:]]

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.

[[Image:]]

Search Engine

The search engine has the purpose of identifying

• the registered object types
• the search destination categories available
• the search providers implementations available

[[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.

View

The view has two main responsibilities:

• to gather the input parameters
• to display the search result

[[Image:]]

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)

[[Image:]]

The sequence diagram below gives some more details on installing the actions into the UI

[[Image:]]

Search Favourites

Search favourites is also built on top of the MVC design pattern

[[Image:]]

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

[[Image:]]

The sequence diagram below illustrates the interaction between view, controller, persistency framework and store providers when an item is being “bookmarked”

[[Image:]]

When the search favourites view is opened the bookmarked items are being loaded

[[Image:]]

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>