Changes between Initial Version and Version 1 of DosAndDontsForApplicationWriters

Timestamp:

Oct 20, 2005, 4:20:32 AM (20 years ago)

Author:

Sune Kirkeby <sune.kirkeby@…>

Comment:

Rough draft of "Do's and Dont's for Application Writers"

DosAndDontsForApplicationWriters

@@ +1 @@
+= 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.
+
+== 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}}}.
+
+= 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.