Do's and Dont's for Application Writers

This is a guide to writing Django applications, the goals I'm aiming for are:

• the application should be easy to install for users
• the application should play nice with other applications

These are the guidelines I would proprose, please comment and discuss. I hope this can become something everyone in the Django community can agree on.

Throughout this document I will need to refer to an imaginary application for examples; let's call it mnemosyne, and put it in ibofobi.apps. When I need to refer to paths, I'll use relative paths rooted at the mnemosyne package directory.

Templates

• To avoid name clashes with templates from other applications all your templates should go into mnemosyne/templates/mnemosyne/
• Your templates should all extend a single base-template specific to your application, in my example it would be mnemosyne/templates/mnemosyne/base.html and all my templates would start with

  {% extends "mnemosyne/base" %}
  

  and the mnemosyne/base template should either be a complete HTML-document, or (and I think this is preferrable) just be

  {% extends "base" %}
  

  (unless you have any pages which should go under the admin, then they should extend admin/base_site.) Should I s/base/base_site/ to be consistent with the admin-application? I personally prefer bare and base over base and base_site; they are more concise and they lack the CTS-inducing underscore.
• Your templates should fill in two blocks: title and content.
• You should refer to media-files with a configurable prefix, in the example a good setting would be MNEMOSYNE_MEDIA_ROOT. For example:

  <link rel='stylesheet' href='{{ MNEMOSYNE_MEDIA_ROOT }}/my.css' />
  

• You should refer to pages in your application with either relative links, or where this is impractical or just plain impossible, with a configurable prefix. In the example I would go with MNEMOSYNE_ROOT.
• Please, please, please. Try to write templates as correct XHTML.

Template tags

• Your application should provide template tags for those features which do not depend on the actual request being handled, for example a hypothetical blog application might provide template tags to get a list of categories, etc. This way sites can easily integrate your application outside your applications own views.

Media files

• Your media-files should go into mnemosyne/media/. Should that be mnemosyne/media/mnemosyne/? It would mirror the templates, and probably looks better in Alias-directives in Apache-configurations ;)

Settings

• Your application should have decent default values for MNEMOSYNE_ROOT and MNEMOSYNE_MEDIA_ROOT, for example /mnemosyne and /media/mnemosyne.

URLs

• What would be a place to expect application-specific admin-URLs to go?

Somewhat related stuff

• A template for an application setup.py:

  try:
      from setuptools import setup
  except ImportError:
      from distutils.core import setup
  setup(name = "mnemosyne",
        author = "Sune Kirkeby",
        url = "http://ibofobi.dk/stuff/mnemosyne/",
        version = '0.1',
        packages = ['ibofobi', 'ibofobi.apps', 'ibofobi.apps.mnemosyne',
                    'ibofobi.apps.mnemosyne.models',
                    'ibofobi.apps.mnemosyne.views',
                    'ibofobi.apps.mnemosyne.urls'],
        package_dir = {'': 'src'},
        package_data = {'ibofobi.apps.mnemosyne': ['templates/mnemosyne/*.html',
                                                   'media/*',],},
        # distutils complain about these, anyone know an easy way to silence it?
        namespace_packages = ['ibofobi.apps'],
        zip_safe = True,
  )
  

• Is templates/<app-name>/ and media/ created by {{{django-admin startapp}}? Should they be?
• It would be nice if doing things this way was more natural in Django, than doing it any other way. For example it would be nice if django.conf.settings was in Context as settings, so templates would have access to MNEMOSYNE_ROOT and MNEMOSYNE_MEDIA_ROOT.
• A ten-minute walk-through of an application might be good, to make the points in this document easier to visualize.

Comments

I would prefer to use django-users for comments and discussions on this document, wikis have very poor threading :) So, if you have comments, or there's something you just plain disagree with, please bring it up there.