Skip to content

Replacing the Person Model

Jump to bottom
chmarr edited this page Nov 28, 2012 · 9 revisions

Artshow Jockey has been designed to be functional as a component in a larger Django installation. It is very likely that such an installation already has some concept of a Person, either a separate model, or an extension to the User model that adds in addresses and phone numbers, etc.

While Artshow Jockey comes with a simple contact manager component, called "peeps", it is intended that this can be replaced with an existing manager with the minimum of fuss.

Instructions

Of note, this needs to be completed before you first run migrate or populate any people, as changes here will significantly alter the database schema. If you need to migrate from one form to another, this is possible but requires advanced knowledge of South data migration techniques.

  • Remove 'peeps' and 'artshow_shims' from your APPLICATIONS setting.
  • Alternately, keep 'artshow_shims', disconnect it from being updated by git (add it to .gitignore), and modify file there to suit your installation.
  • Create a proxy model that can provide the necessary interface (see below) to the Artshow application. You can use the existing proxy in artshow_shims/models.py as a guide. If your person model already provides everything, there is no need to supply a 'shim' and you can simply point there.
  • Create a LookupChannel subclass that can search and display your person objects, but returns a manager for proxy objects above. If your person model already has a LookupChannel, you'll need to inherit from this and change the model to the Proxy model. artshow_shims/lookups.py shows how.
  • Change ARTSHOW_PERSON_CLASS to the appname.modelname of your proxy model.
  • Change AJAX_LOOKUP_CHANNELS so that the artshow_person channel points to your LookupChannel.

Done!

Proxy Model Interface Requirements

  • name - an attribute or property that returns the full name of the person
  • email - an attribute or property that returns an email address
  • mailing_label(self) - an method that returns a multi-line text block suitable for a mailing label.
  • @staticmethod get_search_fields( prefix="person__" ) - returns a list of field names suitable for appending to a "search_fields" attribute on an AdminModel
  • @staticmethod get_search_q( search_str, prefix="person__" ) - returns a Q object suitable for use as a filter on a Person ModelManager when searching for 'search_str'.

See artshow_shims/models.py for a working example.

It was certainly possible to provide peeps.Person in a form that did not require any proxy objects. However, it was done this way to provide a working example. The static methods, in particular, would only be present when attempting a replaceable component such as this, so putting them into the real model would be unrealistic.

Clone this wiki locally