molly.apps.contact – Contact search

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

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 BaseContactProvider and expose the following interface:

class molly.apps.contact.providers.BaseContactProvider
form

A class object inheriting Form to be presented to the user and used for input validation. If not overriden, defaults to GenericContactForm, which presents a single query field.

medium_choices

An attribute consisting of a list of tuples of the media supported by this provider (e.g., phonebook, e-mail address list, etc), where the tuple is the form (‘key’, ‘description’). The key is what is passed as the medium on the normalize_query method, and the description is what is shown to the user.

normalize_query(cleaned_data, medium)

An attribute consisting of a list of tuples of the media supported by this provider (e.g., phonebook, e-mail address list, etc), where the tuple is the form (‘key’, ‘description’). The key is what is passed as the medium on the normalize_query method, and the description is what is shown to the user.

perform_query(**kwargs)

This method performs a contact lookup based on **kwargs.

Each result must be a dictionary containing some subset of the following keys (taken from RFC 4519 which defines standard LDAP attributes):

  • cn (common name)
  • givenName
  • sn (surname)
  • telephoneNumber
  • facsimileTelephoneNumber
  • mail (e-mail addresses)
  • roomNumber
  • title (job role, etc.)
  • ou (organisational unit, e.g. department)

With the exception of cn, all should be lists.

Additionally, a result may contain an id item, containing a unique identifier which may be passed to fetch_result(). ids must be URI-safe and not contain forward slashes.

This can return molly.apps.contact.providers.TooManyResults if the provider (or underlying services) deems that the query has returned “too many results”

fetch_result(id)

May optionally be defined to return the full record for a person, where it is decided that perform_query() should return a subset of the available fields.

If defined, the default results template will provide a link to a page for the individual.

If the ID is invalid, self.NoSuchResult is raised

Views

index

This view lives at the / URL of this app and is handled by 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 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 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)