Edgewall Software

Extension Point : ISearchSource

InterfaceISearchSourceSince0.9
Moduletrac.searchSourceapi.py

The ISearchSource allows extending the search system with additional information sources.

Purpose

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.

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course 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.)

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.

The milestone search is a good example for all of the above.

Available Implementations

In Trac:

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

API History

  • 0.9 introduced the interface.
  • 0.10 changed parameter query string to list of terms. ([2940]; example supporting both APIs)
  • 0.11 refactored trac.Search module into trac.search package. ([4262])
Last modified 7 years ago Last modified on Aug 6, 2011, 2:07:53 PM
Note: See TracWiki for help on using the wiki.