Overview (Quick Search API)

Quick Search API
Package	Description
org.netbeans.spi.quicksearch

Quick Search API in infrastrcuture which enables module clients to plug into Quick Search UI and provide results of search that end user performed in UI. Quick Search UI is represented by a small text field in toolbar area on right hand side, with asociated popup window to show search results.

Clients that want to extend Quick Search capabilities and provide data to search in are expected to implement SearchProvider SPI.

SearchProvider implementations are registered through module's xml layer file, as explained in SearchProvider SPI javadoc and detailed Instantiation rules.

Main task of SearchProvider implementations is to evaluate input SearchRequest, perform search in its data model and feed SearchResponse response object by results apropriate for given request.

quicksearch.web.site Resource name from org.netbeans.modules.quicksearch.web.Bundle where it is possible to specify website to restrict the web search to. When set to e.g. NetBeans.org then the web search provider will search for given text in web pages from NetBeans.org site only. quicksearch.web.url_patterns Resource name from org.netbeans.modules.quicksearch.web.Bundle where it is possible to specify a comma separated list of regular expressions that the search results URLs must contain. When set to e.g. ".*docs/myapp.*,.*tutorials/myapp.*" then all the search results will have either "docs/myapp" or "tutorials/myapp" anywhere in the URL.

What is New (see all changes)?

Use Cases

How To Add New Quick Search Provider

In order to plug in a new Quick Search provider and new category of results, module writers need to complete following steps:

1. Implement SearchProvider

Implement body of SearchProvider.evaluate method like suggested in its javadoc.

2. Register SearchProvider implementation in xml layer

Register your SearchProvider implementation in your module's xml layer file under main "/QuickSearch" folder. Registration xml syntax is following:

              <folder name="QuickSearch">
                  <folder name="Category1_ID">
                      <attr name="position" intvalue="300"/>
                      <file name="org-netbeans-module1-package1-Provider1Impl.instance"/>
                  </folder>
                  <folder name="Category2_ID">
                      <!--Attribute for localization - provide localized display name of category!-->
                      <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.yourmodule.YourBundle"/>
                      <!--Attribute for command prefix - used to narrow search to this category only!-->
                      <attr name="command" stringvalue="p"/>
                      <!--Attribute for category ordering!-->
                      <attr name="position" intvalue="200"/>
                      <!--Note that multiple providers can contribute to one category!-->
                      <file name="org-netbeans-module2-package2-Provider2Impl.instance"/>
                      <file name="org-netbeans-module2-package3-Provider3Impl.instance"/>
                  </folder>
              </folder>

Syntax explanation:

Subfolders of "QuickSearch" define search result categories and their order.
Providers can share category by putting themselves under same subfolder.
Ordering of categories is done through NetBeans standard FileSystem API ordering "position" attribute
Display name of category folder uses NetBeans standard FileSystem API "SystemFileSystem.localizingBundle" attribute.
"command" attribute defines command prefix for category, which is used to narrow Quick Search to only one category. Provide short prefix, ideally containing one or two prefix, that will serve as command to narrow search only this category. In above syntax example, if user types 'p' and space key and then text, only "Category2_ID" category will be searched.
If several providers share one category, then only one provider needs to specify above attributes. Note however that if your provider shares category with provider from different module, you should have dependency on module which actually define those attributes. Dependency assures there will always be category "description" for category that you are sharing.

How To Share Category Of Results

Quick Search UI shows search results divided into visually separeted sections, called categories. Several SearchProvider implementations may decide to display their results in one shared category of results in Quick Search UI.

In order to share category, module writers have to agree on shared category and its properties, especially its name. It means that all providers (possibly in different NetBeans modules) need to be registered under the same folder, as shown below:

Provider 1

Provider 1 is category "owner", which defines properties of SharedCategory such as display name, position and command prefix.

              <folder name="QuickSearch">
                  <folder name="SharedCategory">
                      <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.yourmodule.YourBundle"/>
                      <attr name="command" stringvalue="p"/>
                      <attr name="position" intvalue="200"/>
                      <file name="org-netbeans-module1-package1-Provider1Impl.instance">
                          <attr name="position" intvalue="300"/>
                      </file>                          
                  </folder>
              </folder>

Provider 2

Other providers from other modules are sharing category with Provider 1. Provider 2 does not define properties of SharedCategory, as they were already defined by Provider 1. Note that module dependency on the module of Provider 1 is needed to ensure that SharedCategory is fully defined.

              <folder name="QuickSearch">
                  <folder name="SharedCategory">
                      <file name="org-netbeans-module2-package2-Provider2Impl.instance"/>
                          <attr name="position" intvalue="200"/>
                      </file>                          
                  </folder>
              </folder>

Provider 3

The same rules apply like for Provider 2. Note that position attribute can be used to control position of provider's results in shared category. Results from provider with lowest position will go first and so on.

              <folder name="QuickSearch">
                  <folder name="SharedCategory">
                      <file name="org-netbeans-module2-package3-Provider3Impl.instance"/>
                          <attr name="position" intvalue="100"/>
                      </file>                          
                  </folder>
              </folder>

How To Define and Modify Order of Categories

Order of categories of results can be set by using "position" attribute of category xml folder definition. Following example will result in FirstCategory to be first, and SecongCategory to be second :), which means that FirstCategory and its results will be displayed above Secondcategory in QuickSearch results window.

              <folder name="QuickSearch">
                  <folder name="SecondCategory">
                      <attr name="position" intvalue="300"/>
                      ...
                  </folder>
                  <folder name="FirstCategory">
                      <attr name="position" intvalue="200"/>
                      ...
                  </folder>
             </folder>

How To Hide Recent Searches Results and Others

"Recent Searches" provider is contained directly in spi.quicksearch module, so its functionality is automatically always available by default. However, if your module wants to disable "Recent Searches" or any other category, follow the steps below:

Define module dependency

Your module have to depend on module where provider you want to disable is contained. In case of "Recent Searches" provider, it's spi,quicksearch, on which you probably already depend.

Disable provider using "_hidden"

For example, to disable "Recent Searches" provider, write into your layer:

              <folder name="QuickSearch">
                  <folder name="Recent_hidden">
                  </folder>
              </folder>

"Recent" is a name of category for "Recent Searches" provider and by appending "_hidden" suffix you are telling system to "hide" it. This technique can be used also to disable invidual search providers.

How To Use Quick Search in Platform Application

Quick Search UI is disabled by default in application built on top of NetBeans platform. To enable Quick Search feature in your application, complete following steps:

1. Write XML layer registration

Add the following lines to XML layer of some of your modules in your application suite:

        <folder name="Toolbars">
            <folder name="QuickSearch">
            <attr name="SystemFileSystem.localizingBundle" stringvalue="com.myapp.mymodule.MyBundle"/>
                <file name="org-netbeans-modules-quicksearch-QuickSearchAction.shadow">
                    <attr name="originalFile" stringvalue="Actions/Edit/org-netbeans-modules-quicksearch-QuickSearchAction.instance"/>
                </file>
            </folder>
        </folder>

2. Localize Toolbar Name

Replace com.myapp.mymodule.MyBundle in the xml registration above with path to your properties file, in which you'll define localized name of Quick Search toolbar:

                Toolbars/QuickSearch=Quick Search

By default, providers for searching in actions and recent searches will be enabled. Web search provider is disabled by default, see use case below for info how to turn it on.

How To Add a Default Web Search Provider

There is a default implementation of web search provider which uses Google to search for the given text on the web. Simply add the following lines to your XML layer to enable this search provider in your application:

          <folder name="QuickSearch">
              <folder name="WebSearch">
                  <!--Attribute for localization - provide localized display name of category!-->
                  <attr name="SystemFileSystem.localizingBundle" stringvalue="com.myapp.mymodule.MyBundle"/>
                  <!--Attribute for command prefix - used to narrow search to this category only!-->
                  <attr name="command" stringvalue="g"/>
                  <!--Attribute for category ordering!-->
                  <attr name="position" intvalue="200"/>
                  <!--Note that multiple providers can contribute to one category!-->
                  <file name="org-netbeans-modules-quicksearch-web-WebQuickSearchProviderImpl.instance"/>
              </folder>
          </folder>

You can also add branding for org.netbeans.modules.quicksearch.web Bundle to restrict the search to a particular site only:

            quicksearch.web.site=mywebsite.com

And you can also restrict the search to some parts your website only:

            quicksearch.web.url_patterns=mywebsite.com/docs,mywebsite.com/files/tutorials

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...

Group of java interfaces

Interface Name	In/Out	Stability	Specified in What Document?
SearchProvider	Exported	Official	.../spi/quicksearch/SearchProvider.html
SearchRequest	Exported	Official	.../spi/quicksearch/SearchRequest.html
SearchResponse	Exported	Official	.../spi/quicksearch/SearchResponse.html

Group of property interfaces

Interface Name	In/Out	Stability	Specified in What Document?
quicksearch.web.site	Exported	Under Development	Resource name from org.netbeans.modules.quicksearch.web.Bundle where it is possible to specify website to restrict the web search to. When set to e.g. NetBeans.org then the web search provider will search for given text in web pages from NetBeans.org site only.
quicksearch.web.url_patterns	Exported	Under Development	Resource name from org.netbeans.modules.quicksearch.web.Bundle where it is possible to specify a comma separated list of regular expressions that the search results URLs must contain. When set to e.g. ".docs/myapp.,.tutorials/myapp." then all the search results will have either "docs/myapp" or "tutorials/myapp" anywhere in the URL.

Implementation Details

Where are the sources for the module?

The sources for the module are in the NetBeans Mercurial repositories.

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

Nothing, regular depencency is enough.

Read more about the implementation in the answers to architecture questions.

Quick Search APIOfficial