:mod:`molly.apps.contact` -- Contact search
===========================================
.. module :: molly.apps.contact
This application provides contact search functionality
Configuration
-------------
* provider: the provider which provides contact search results
Sample::
Application('molly.apps.contact', 'contact', 'Contact search',
provider = Provider('molly.apps.contact.providers.LDAPContactProvider'
url='ldap://ldap.mit.edu:389', base_dn='dc=mit,dc=edu'),
),
Providers
---------
:class:`molly.apps.contact.providers.LDAPContactProvider`
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This queries an LDAP server for contact details. It takes three options:
* url: The URL to the LDAP server to use
* base_dn: The base DN to use when searching the LDAP tree
* phone_prefix (optional, defaults to blank): A prefix to add to phone numbers,
e.g., if your LDAP servers only store extension numbers, you can add the
prefix to make it externally callable here (e.g., '+44190443'). This is not
used when ``phone_formatter`` is set.
* phone_formatter (optional, defaults to nothing): A custom "number formatter".
The option expects to have a callable (either a function defined elsewhere
in your settings file, or a lambda defined there) which is called with the
raw phone number from LDAP and is expected to return a normalised phone
number. Use this is you need more advanced logic than the phone_prefix option
can give you.
* alphabetical (defaults to False): A boolean which indicates whether or not
results from the LDAP server should be sorted alphabetically by surname.
* query (defaults to '(sn={surname})'): This is the query which is passed to
the LDAP server. It uses new style string formatting and has two fields
available 'forename' and surname.
Writing Your Own Providers
--------------------------
A contact provider must inherit :class:`~molly.apps.contact.providers.BaseContactProvider`
and expose the following interface:
.. autoclass:: molly.apps.contact.providers.BaseContactProvider
.. autoattribute :: molly.apps.contact.providers.BaseContactProvider.form
.. autoattribute :: molly.apps.contact.providers.BaseContactProvider.medium_choices
.. automethod :: molly.apps.contact.providers.BaseContactProvider.normalize_query
.. automethod :: molly.apps.contact.providers.BaseContactProvider.perform_query
.. automethod :: molly.apps.contact.providers.BaseContactProvider.fetch_result
Views
-----
``index``
"""""""""
This view lives at the ``/`` URL of this app and is handled by
:class:`molly.apps.contact.views.IndexView`.
This view renders ``contact/index.html``, providing the following context:
* ``form``: A `form `_
defined by the provider to use as the input for searching
* ``medium_choices``: A list of tuples, representing the different media the
provider can search (e.g., phone book, e-mail address list), in the format
specified by
There are no overridable blocks provided by this template, but the search form
is rendered by the separate template ``contact/search_form.html``
``result_list``
"""""""""""""""
This view lives at ``results/`` in this app and is handled by
:class:`molly.apps.contact.views.ResultListView`.
This view renders ``contact/result_list.html`` providing the following context:
* ``form``: The `form `_
used to perform the search
* ``medium``: The medium selected for this query
* ``results``: The list of results (as returned by `molly.apps.contact.providers.BaseContactProvider.perform_query`)
* ``message``: If set, any error messages generated in the search
There are no overridable blocks provided by this template, but each individual
result is rendered by ``contact/result.html``
``result_detail``
"""""""""""""""""
The view lives at ``results/:ID:`` in this app, and is handled by
:class:`molly.apps.contact.views.ResultDetailView`.
This view renders ``contact/result_detail.html`` providing the following
context:
* ``result``: The result object (as returned by `molly.apps.contact.providers.BaseContactProvider.perform_query`
to be rendered)