Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.search.api.ISearchSource

Timestamp:

Aug 6, 2011, 2:07:53 PM (13 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.search.api.ISearchSource

@@ +1 @@
+== Extension Point : ''ISearchSource'' ==
+
+||'''Interface'''||''ISearchSource''||'''Since'''||0.9||
+||'''Module'''||''trac.search''||'''Source'''||[source:trunk/trac/search/api.py api.py]||
+
+The ''ISearchSource'' allows extending the search system with additional information sources.
+
+== Purpose ==
+
+Trac provides a unified [TracSearch search system] for full-text search in any resources. By default it supports searching tickets, wiki pages, changesets and milestones.
+However plugins can implement arbitrary search sources allowing the user to search its resources or any other data of interest.
+
+== Usage ==
+
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
+
+The implementation reports the supported filters and whether they should be enabled by default. It is then called when a user performs a search, and should return any results matching the search terms for any relevant enabled filters.
+
+The `trac.search.api` module also provides some helper functions that can often be used to implement the search itself (`search_to_sql`) or to format the results appropriately (`shorten_result`).
+
+== Examples ==
+
+The following example implements a simple search source for user names. (Note that Trac stores names of authenticated users in the `sid` field of the `session` table.)
+{{{
+#!python
+from datetime import datetime
+from trac.core import *
+from trac.search import ISearchSource, search_to_sql
+from trac.util.datefmt import utc
+
+class UserSearchModule(Component):
+    """Search user names."""
+
+    implements(ISearchSource)
+
+    # ISearchSource methods
+
+    def get_search_filters(self, req):
+        yield ('usernames', 'User Names', False)
+
+    def get_search_results(self, req, terms, filters):
+        if not 'usernames' in filters:
+            return
+        with self.env.db_query as db:
+            sql_query, args = search_to_sql(db, ['sid'], terms)
+
+            for name, last_visit in db("""
+                    SELECT sid, last_visit FROM session
+                    WHERE authenticated=1 AND """ + sql_query, args):
+                dt = last_visit if last_visit else datetime.now(utc)
+                args = '?owner=%s&or&reporter=%s' % (name, name)
+                link = req.href.query() + args
+                yield (link, name, dt, '', '')
+}}}
+
+In this example the search result consists simply of a title (the matching name), a date (when the user last visited this Trac instance) and a query link (tickets owned or reported by that user).
+
+More traditional implementations would show resources as search results, with title (retrieved by `get_resource_name`), URL (`get_resource_url`), excerpt (`shorten_result`) and possibly an author and creation date.
+
+Often such implementations would also perform ''permission checks'' (and possibly implement [../trac.perm.IPermissionRequestor IPermissionRequestor]). The user might not have permission to search the subsystem at all, or certain individual search results (resources) might need to be filtered out.
+
+The [source:trunk/trac/ticket/roadmap.py milestone search] is a good example for all of the above.
+
+== Available Implementations ==
+In Trac:
+|| [source:trunk/trac/ticket/web_ui.py TicketModule] || Searches ticket text fields and attachments. ||
+|| [source:trunk/trac/wiki/web_ui.py WikiModule] || Searches wiki pages and attachments. ||
+|| [source:trunk/trac/versioncontrol/web_ui/changeset.py ChangesetModule] || Searches changesets (in the repository cache). ||
+|| [source:trunk/trac/ticket/roadmap.py MilestoneModule] || Searches milestone name, description and attachments. ||
+
+In third-party plugins:
+|| th:SearchAllPlugin || Searches all Trac projects in the Trac multi-project environment. ||
+|| th:RepoSearchPlugin || Searches the source code repository (using a custom indexer). ||
+|| th:FilenameSearchPlugin || Searches filenames in the source code repository. ||
+|| th:SearchAttachmentsPlugin || Searches attachments (using the ''Swish-e'' indexer). ||
+|| th:TracFormsPlugin || Provides (searchable) Forms anywhere on Trac. ||
+|| th:DoxygenPlugin || Integrates (searchable) doxygen documentation. ||
+|| th:PyDocPlugin || Integrates (searchable) pydoc documentation. ||
+
+== Additional Information and References ==
+ * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.search.api.ISearchSource-class.html Epydoc API Reference]
+ * See TracSearch for user documentation of the search system
+ * See AdvancedSearch for possible improvements
+ * [/query?status=!closed&component=search+system Related tickets]
+
+==== API History ====
+ * 0.9 introduced the interface.
+ * [wiki:TracDev/ApiChanges/0.10#ISearchSource 0.10] changed parameter `query` string to list of `terms`. ([2940]; [th:changeset:459 example] supporting both APIs)
+ * [wiki:TracDev/ApiChanges/0.11#ISearchSource 0.11] refactored `trac.Search` module into `trac.search` package. ([4262])