| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <!-- Generated by javadoc (1.8.0_181) on Fri Sep 14 11:37:47 BST 2018 --> |
| <title>Overview (Quick Search API)</title> |
| <meta name="date" content="2018-09-14"> |
| <link rel="stylesheet" type="text/css" href="javadoc.css" title="Style"> |
| <script type="text/javascript" src="script.js"></script> |
| </head> |
| <body> |
| <script type="text/javascript"><!-- |
| try { |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="Overview (Quick Search API)"; |
| } |
| } |
| catch(err) { |
| } |
| //--> |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar.top"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.top.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li class="navBarCell1Rev">Overview</li> |
| <li><a href="org/netbeans/spi/quicksearch/package-summary.html">Package</a></li> |
| <li>Class</li> |
| <li>Use</li> |
| <li><a href="org/netbeans/spi/quicksearch/package-tree.html">Tree</a></li> |
| <li><a href="deprecated-list.html">Deprecated</a></li> |
| <li><a href="index-files/index-1.html">Index</a></li> |
| <li><a href="help-doc.html">Help</a></li> |
| </ul> |
| <div class="aboutLanguage">org.netbeans.spi.quicksearch 1.29.1 </div> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li>Prev</li> |
| <li>Next</li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="index.html?overview-summary.html" target="_top">Frames</a></li> |
| <li><a href="overview-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_top"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <div class="header"> |
| <h1 class="title">Quick Search API<br/><span style='font-style:normal; font-size:medium; font-weight:normal; background-color:#ffffff;'><a href='http://wiki.netbeans.org/API_Stability#Official' target='_blank'>Official</a></span></h1> |
| </div> |
| <div class="header"> |
| <p>See: <a href="#overview.description">Description</a></p> |
| </div> |
| <div class="contentContainer"> |
| <table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Quick Search API table, listing packages, and an explanation"> |
| <caption><span>Quick Search API</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Package</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="org/netbeans/spi/quicksearch/package-summary.html">org.netbeans.spi.quicksearch</a></td> |
| <td class="colLast"> </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="contentContainer"><a name="overview.description"> |
| <!-- --> |
| </a> |
| <div class="block"><p> |
| |
| <p> |
| 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. |
| </p> |
| |
| |
| <p> |
| Clients that want to extend Quick Search capabilities and provide data to search in |
| are expected to implement <a href="org/netbeans/spi/quicksearch/SearchProvider.html">SearchProvider</a> |
| SPI.</p> |
| |
| |
| <p>SearchProvider implementations are registered through module's xml layer file, |
| as explained in <a href="org/netbeans/spi/quicksearch/SearchProvider.html" shape="rect">SearchProvider SPI</a> |
| javadoc and detailed <a href="../org-openide-util/org/openide/util/doc-files/api.html#instances" shape="rect">Instantiation rules</a>. |
| </p> |
| |
| |
| <p>Main task of SearchProvider implementations is to evaluate input |
| <a href="org/netbeans/spi/quicksearch/SearchRequest.html">SearchRequest</a>, |
| perform search in its data model and feed <a href="org/netbeans/spi/quicksearch/SearchResponse.html">SearchResponse</a> |
| response object by results apropriate for given request. |
| </p> |
| 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. |
| |
| </p> |
| <h3>What is New (see <a href="apichanges.html">all changes</a>)?</h3> |
| <ul> |
| |
| |
| <!--Search for dates that are later or equal to 1997-09-01 in |
| .--> |
| </ul> |
| <h3>Use Cases</h3> |
| <answer id="arch-usecases"> |
| |
| <p> |
| |
| |
| <h5>How To Add New Quick Search Provider</h5> |
| In order to plug in a new Quick Search provider and new category of results, |
| module writers need to complete following steps: |
| |
| <h5>1. Implement <a href="org/netbeans/spi/quicksearch/SearchProvider.html" shape="rect">SearchProvider</a> |
| </h5> |
| |
| <ul> |
| |
| <li>Implement body of <b><code>SearchProvider.evaluate</code></b> method |
| like suggested in its <a href="org/netbeans/spi/quicksearch/SearchProvider.html" shape="rect">javadoc</a>. |
| </li> |
| |
| </ul> |
| |
| |
| <h5>2. Register SearchProvider implementation in xml layer</h5> |
| Register your SearchProvider implementation in your module's xml layer file under |
| main <b>"/QuickSearch"</b> folder. Registration xml syntax is following: |
| |
| <pre xml:space="preserve"> |
| <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> |
| </pre> |
| |
| |
| <b>Syntax explanation:</b> |
| |
| <ul> |
| |
| <li>Subfolders of "QuickSearch" define search result categories and their order.</li> |
| |
| <li>Providers can share category by putting themselves under same subfolder.</li> |
| |
| <li>Ordering of categories is done through NetBeans standard FileSystem API ordering |
| "position" attribute</li> |
| |
| <li>Display name of category folder uses NetBeans standard FileSystem API |
| "SystemFileSystem.localizingBundle" attribute.</li> |
| |
| <li>"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.</li> |
| |
| <li>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.</li> |
| |
| </ul> |
| |
| |
| |
| |
| <h5>How To Share Category Of Results</h5> |
| |
| <p>Quick Search UI shows search results divided into visually separeted sections, |
| called categories. Several <code>SearchProvider</code> implementations may decide to display |
| their results in one shared category of results in Quick Search UI.</p> |
| |
| |
| <p>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:</p> |
| |
| |
| <h5>Provider 1</h5> |
| Provider 1 is category "owner", which defines properties of <code>SharedCategory</code> such as |
| display name, position and command prefix. |
| <pre xml:space="preserve"> |
| <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> |
| </pre> |
| |
| |
| <h5>Provider 2</h5> |
| Other providers from other modules are sharing category with Provider 1. |
| Provider 2 does not define properties of <code>SharedCategory</code>, |
| as they were already defined by Provider 1. |
| Note that module dependency on the module of Provider 1 is needed |
| to ensure that <code>SharedCategory</code> is fully defined. |
| <pre xml:space="preserve"> |
| <folder name="QuickSearch"> |
| <folder name="SharedCategory"> |
| <file name="org-netbeans-module2-package2-Provider2Impl.instance"/> |
| <attr name="position" intvalue="200"/> |
| </file> |
| </folder> |
| </folder> |
| </pre> |
| |
| |
| <h5>Provider 3</h5> |
| 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. |
| <pre xml:space="preserve"> |
| <folder name="QuickSearch"> |
| <folder name="SharedCategory"> |
| <file name="org-netbeans-module2-package3-Provider3Impl.instance"/> |
| <attr name="position" intvalue="100"/> |
| </file> |
| </folder> |
| </folder> |
| </pre> |
| |
| |
| |
| <h5>How To Define and Modify Order of Categories</h5> |
| Order of categories of results can be set by using "position" attribute |
| of category xml folder definition. Following example will result in |
| <code>FirstCategory</code> to be first, and <code>SecongCategory</code> to be second :), |
| which means that <code>FirstCategory</code> and its results will be |
| displayed above <code>Secondcategory</code> in QuickSearch results window. |
| |
| <pre xml:space="preserve"> |
| <folder name="QuickSearch"> |
| <folder name="SecondCategory"> |
| <attr name="position" intvalue="300"/> |
| ... |
| </folder> |
| <folder name="FirstCategory"> |
| <attr name="position" intvalue="200"/> |
| ... |
| </folder> |
| </folder> |
| </pre> |
| |
| |
| |
| <h5>How To Hide Recent Searches Results and Others</h5> |
| "Recent Searches" provider is contained directly in <code>spi.quicksearch</code> |
| 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: |
| |
| <h5>Define module dependency</h5> |
| Your module have to depend on module where provider you want to disable |
| is contained. In case of "Recent Searches" provider, it's <code>spi,quicksearch</code>, |
| on which you probably already depend. |
| |
| <h5>Disable provider using "_hidden"</h5> |
| For example, to disable "Recent Searches" provider, write into your layer: |
| |
| <pre xml:space="preserve"> |
| <folder name="QuickSearch"> |
| <folder name="Recent_hidden"> |
| </folder> |
| </folder> |
| </pre> |
| |
| "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. |
| |
| |
| <h5>How To Use Quick Search in Platform Application</h5> |
| 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: |
| |
| <h5>1. Write XML layer registration</h5> |
| Add the following lines to XML layer of some of your modules in your |
| application suite: |
| |
| <pre xml:space="preserve"> |
| <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> |
| </pre> |
| |
| |
| <h5>2. Localize Toolbar Name</h5> |
| Replace <code>com.myapp.mymodule.MyBundle</code> in the xml registration |
| above with path to your properties file, in which you'll define |
| localized name of Quick Search toolbar: |
| <pre xml:space="preserve"> |
| Toolbars/QuickSearch=Quick Search |
| </pre> |
| |
| |
| <p>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.</p> |
| |
| |
| |
| <h5>How To Add a Default Web Search Provider</h5> |
| 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: |
| <pre xml:space="preserve"> |
| <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> |
| </pre> |
| You can also add branding for <code>org.netbeans.modules.quicksearch.web</code> Bundle to restrict |
| the search to a particular site only: |
| <pre xml:space="preserve"> |
| quicksearch.web.site=mywebsite.com |
| </pre> |
| And you can also restrict the search to some parts your website only: |
| <pre xml:space="preserve"> |
| quicksearch.web.url_patterns=mywebsite.com/docs,mywebsite.com/files/tutorials |
| </pre> |
| |
| |
| |
| <h5>How to customize Look&Feel properties</h5> |
| If you need to adjust border of the Quick Search component for your |
| Look&Feel, you can put a <code>Border</code> instance into |
| <code>UIManager</code> under key <code>nb.quicksearch.border</code>. |
| |
| </p> |
| |
| </answer> |
| <h3>Exported Interfaces</h3> |
| |
| 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. <a href="architecture-summary.html">Read them all</a>... |
| |
| |
| <a name="group-java"> |
| <h5>Group of java interfaces</h5> |
| </a> |
| <table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%"> |
| <tr> |
| <td> |
| <table border="0" cellpadding="3" cellspacing="1" width="100%"> |
| <tr class="tablersh"> |
| <td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td> |
| </tr> |
| <tr class="tabler"> |
| <td>SearchProvider</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Official">Official</a></td><td><a name="java-SearchProvider"><a href="org/netbeans/spi/quicksearch/SearchProvider.html"> |
| .../spi/quicksearch/SearchProvider.html</a> |
| <p></p> |
| </a></td> |
| </tr> |
| <tr class="tabler"> |
| <td>SearchRequest</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Official">Official</a></td><td><a name="java-SearchRequest"><a href="org/netbeans/spi/quicksearch/SearchRequest.html"> |
| .../spi/quicksearch/SearchRequest.html</a> |
| <p></p> |
| </a></td> |
| </tr> |
| <tr class="tabler"> |
| <td>SearchResponse</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Official">Official</a></td><td><a name="java-SearchResponse"><a href="org/netbeans/spi/quicksearch/SearchResponse.html"> |
| .../spi/quicksearch/SearchResponse.html</a> |
| <p></p> |
| </a></td> |
| </tr> |
| </table> |
| </td> |
| </tr> |
| </table> |
| <p></p> |
| <a name="group-property"> |
| <h5>Group of property interfaces</h5> |
| </a> |
| <table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%"> |
| <tr> |
| <td> |
| <table border="0" cellpadding="3" cellspacing="1" width="100%"> |
| <tr class="tablersh"> |
| <td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td> |
| </tr> |
| <tr class="tabler"> |
| <td>quicksearch.web.site</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Devel">Under Development</a></td><td><a name="property-quicksearch.web.site"> |
| <p></p> |
| 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. |
| <p></p> |
| </a></td> |
| </tr> |
| <tr class="tabler"> |
| <td>quicksearch.web.url_patterns</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Devel">Under Development</a></td><td><a name="property-quicksearch.web.url_patterns"> |
| <p></p> |
| 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. |
| <p></p> |
| </a></td> |
| </tr> |
| </table> |
| </td> |
| </tr> |
| </table> |
| <p></p> |
| <h3>Implementation Details</h3> |
| <h5>Where are the sources for the module?</h5> |
| |
| <p> |
| <p> |
| The sources for the module are in the |
| <a href="http://hg.netbeans.org/" shape="rect">NetBeans Mercurial repositories</a>. |
| </p> |
| </p> |
| |
| <h5>What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?</h5> |
| |
| <p> |
| Nothing, regular depencency is enough. |
| </p> |
| |
| <p> |
| Read more about the implementation in the <a href="architecture-summary.html">answers to |
| architecture questions</a>. |
| </p></div> |
| </div> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar.bottom"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.bottom.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li class="navBarCell1Rev">Overview</li> |
| <li><a href="org/netbeans/spi/quicksearch/package-summary.html">Package</a></li> |
| <li>Class</li> |
| <li>Use</li> |
| <li><a href="org/netbeans/spi/quicksearch/package-tree.html">Tree</a></li> |
| <li><a href="deprecated-list.html">Deprecated</a></li> |
| <li><a href="index-files/index-1.html">Index</a></li> |
| <li><a href="help-doc.html">Help</a></li> |
| </ul> |
| <div class="aboutLanguage">org.netbeans.spi.quicksearch 1.29.1 </div> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li>Prev</li> |
| <li>Next</li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="index.html?overview-summary.html" target="_top">Frames</a></li> |
| <li><a href="overview-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_bottom"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| <p class="legalCopy"><small><span class="footnote">Built on September 14 2018. | Copyright © 2017-2018 Apache Software Foundation. All Rights Reserved.</span></small></p> |
| </body> |
| </html> |
