Extension Point : ISearchSource
The ISearchSource allows extending the search system with additional information sources.
Trac provides a unified 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.
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.
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 (
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
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 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.
|TicketModule||Searches ticket text fields and attachments.|
|WikiModule||Searches wiki pages and attachments.|
|ChangesetModule||Searches changesets (in the repository cache).|
|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
- Epydoc API Reference
- See TracSearch for user documentation of the search system
- See AdvancedSearch for possible improvements
- Related tickets