: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 formatter is set.
 * phone_formatter (optional, defaults to nothing): A custom "number formatter",
   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.

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 <http://docs.djangoproject.com/en/dev/topics/forms/>`_
   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 <http://docs.djangoproject.com/en/dev/topics/forms/>`_
   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)