:mod:`molly.apps.search` -- Whole site search
=============================================
.. module :: molly.apps.search
The search application allows the user to enter a query and retrieve results
from across the site. Results are produced by the application's providers,
and may determine results in whatever manner they choose.
Search providers may access an index for the entire site, or be
application-specific. An institution may have a `Google Search Appliance
`_ from which results are retrieved,
or alternatively they may wish searches for ISBNs to go straight to a library
catalogue page.
Configuration
-------------
* form (optional, defaults to a built-in form): A Django form to use when
searching
* query_expansion_file: A file to use for query expansion
* providers: A list of providers of search results
Sample::
Application('molly.apps.search', 'search', 'Search',
providers = [
Provider('molly.apps.search.providers.ApplicationSearchProvider'),
Provider('molly.apps.search.providers.GSASearchProvider',
search_url = 'http://googlesearch.oucs.ox.ac.uk/search',
domain = 'm.ox.ac.uk',
params = {
'client': 'oxford',
'frontend': 'mobile',
},
title_clean_re = r'm\.ox \| (.*)',
),
],
query_expansion_file = os.path.join(project_root, 'data', 'query_expansion.txt'),
display_to_user = False,
),
Providers
---------
:class:`~molly.providers.apps.search.GSASearchProvider`
"""""""""""""""""""""""""""""""""""""""""""""""""""""""
This search provider retrieves results from a :abbr:`GSA (Google Search
Appliance)` as XML. Results are augmented using
:meth:`~molly.apps.search.providers.BaseSearchProvider.get_metadata`.
Options:
* search_url: The URL of the GSA
* domain: The domain of your deployment (used to restrict search results to)
* params (optional, defaults to nothing): Optional parameters to pass with the
search request
* title_clean_re (optional, defaults to nothing): A regular expression to tidy
up page titles when returned
:data:`params` are added to the query string of the URL used when fetching
request from the :abbr:`GSA`. Further information about valid parameters can
be found in `the Google Seach Appliance documentation
`_.
Where provided, :data:`title_clean_re` is a regular expression containing a
single group (i.e. paranthesised expression). If the title of a page as
returned by the :abbr:`GSA` matches the regular expression, it is substituted
with the matched group. This can be used to remove common elements of titles.
:class:`~molly.apps.search.providers.ApplicationSearchProvider`
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This provider allows for Molly apps to return search results (e.g., library
books, places, etc). It has no options.
Adding Search Capability to your App
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. todo::
Writing Your Own Providers
--------------------------
Providers should extend the
:class:`~molly.apps.search.providers.BaseSearchProvider` interface:
.. autoclass:: molly.apps.search.providers.BaseSearchProvider
.. automethod :: molly.apps.search.providers.BaseSearchProvider.perform_search
:class:`~molly.apps.search.providers.BaseSearchProvider` also provides the
following utility methods you may find useful in your implementations:
.. autoclass:: molly.apps.search.providers.BaseSearchProvider
.. automethod :: molly.apps.search.providers.BaseSearchProvider.get_metadata
Search results
""""""""""""""
Individual search results are represented as dictionaries where the following
keys have particular meanings:
:const:`url` (*required*)
The local part of the URL for the page. Will be used as an :attr:`href`.
:const:`title` (*required*)
The page title.
:const:`application` (*recommended*)
The name of the application that handles the URL. May be used to display
an icon next to each result.
:const:`excerpt`
The bit of the page relevant to the query. May contain HTML (i.e. should
be marked safe in a template).
:const:`additional`
More information about the resource represented at the URL. For example,
the :mod:`~molly.apps.places` application returns the type of entity and
a distance from the user's location.
:const:`redirect_if_sole_result`
A boolean, default :const:`False`, which will cause the search page to
redirect to the URL if only one result is returned.
:const:`exclude_from_search`
A boolean, default :const:`False`, which will exclude the page from any
displayed search results. Can be used to exclude irrelevant results or
those not intended for mobile devices.
Views
-----
This application defines just one view:
``index``
"""""""""
Presents a single-field form to the user, and where a query has been
submitted retrieves results from all configured search providers.
Results from multiple providers are presented in the order they were
configured, i.e. the topmost configured provider's results are given
precedence. Where more than one provider returns the same result, metadata
are combined (with the location given by its first occurance) and only one
result is displayed.
This view renders to the :file:`search/index.html` template, passing a
:class:`~molly.apps.search.forms.SearchForm` instance as :data:`form` and
(where a search has been performed) a list of results as :data:`results`.
Query Expansion
---------------
.. todo::