docs/django.rst

   1 Django implementation
   2 ======================
   3
   4 The pgweb application is a fairly simple django application, since
   5 there is no requirement for advanced logic anywhere on the site.
   6
   7 Actual coding practices are, as usual, not fully documented here. When
   8 developing new functionality, please look at an existing application
   9 in the pgweb/ directory that does something similar, and use the
  10 coding practices used there.
  11
  12 Functions and classes should be documented in-line, through comments
  13 or docstrings.
  14
  15 The site is currently deployed on Django 1.4 (being the standard version
  16 in Debian Wheezy), so all testing should be done against this version.
  17
  18 Database access
  19 ---------------
  20 In all places where database access is simple, the django ORM is used
  21 to access the data. In the few places where more advanced queries are
  22 necessary, direct queries to the database are used. There is no
  23 intention to keep the database structure independent of database
  24 used - it's all designed to use PostgreSQL. Therefore, using PostgreSQL
  25 specific syntax in these direct queries is not a problem.
  26
  27 Module split
  28 ------------
  29 The module split is not particularly strict, and there is a lot of
  30 cross-referencing between the modules. This is expected...
  31
  32 Settings
  33 --------
  34 All settings should be listed including their default values in the
  35 shipped settings.py. Modifications should always be made in the
  36 settings_local.py file (which is in .gitignore) to make sure they're
  37 not accidentally committed to the main repository, or cause merge conflicts.
  38
  39 Forms
  40 -----
  41 here are some special things to consider when dealing with forms. For
  42 any objects that are going to be moderated, the Model that is used
  43 should set the send_notification attribute to True. This will cause
  44 the system to automatically send out notifications to the NOTIFICATION_EMAIL
  45 address whenever a new object is created or an existing one is modified.
  46
  47 If the form contains any text fields that accept markdown, the
  48 attribute markdown_fields should be set to a tuple containing a list
  49 of these fields. This will cause the system to automatically generate
  50 preview boxes both in the admin interface (provided it's properly
  51 registered) and on the regular forms.
  52
  53 If the model contains a field for "submitter", it will automatically
  54 be filled in with the current user - be sure to exclude it from the
  55 form itself.
  56
  57 Utilities
  58 ---------
  59 The util/ subdirectory represents a set of utility functions and
  60 classes, rather than an actual application. This is where common code
  61 is put, that may be used between multiple modules.
  62
  63 pgweb.util.admin
  64 ++++++++++++++++
  65 This module contains functionality to help simplify the admin.py
  66 files. In particular, it contains a MarkdownPreviewAdmin class and a
  67 register_markdown function, which are used to register a model to the
  68 admin interface in a way that will make all text fields that are
  69 listed as markdown capable have a preview box in the admin interface.
  70
  71 auth.py
  72 +++++++
  73 This module implements the community login provider for logging into
  74 both the website itself and the admin interface.
  75
  76 contexts.py
  77 +++++++++++
  78 This module implements custom contexts, which is used to implement the
  79 site navigation.
  80
  81 decorators.py
  82 +++++++++++++
  83 This module implements custom decorators used to change view
  84 behavior. This includes decorator ssl_required that makes a view
  85 require an SSL connection to work, and also nocache and cache
  86 decorators that control how long a page can be cached by the frontend
  87 servers.
  88
  89 helpers.py
  90 ++++++++++
  91 This module implements helper functions and classes wrapping standard
  92 django functionality to make for less coding, such as form, template
  93 and XML management.
  94
  95 middleware.py
  96 +++++++++++++
  97 This module implements a custom django middleware, that will take care
  98 of redirecting requests to SSL when required (this is controlled by
  99 the decorator @require_ssl). It will also enable "standard" django
 100 workarounds for getting access to the user who is currently executing
 101 the request as part of thread local storage.
 102
 103 misc.py
 104 +++++++
 105 This module implements misc functions, for things like formatting
 106 strings and sending email.
 107
 108 moderation.py
 109 +++++++++++++
 110 This module implements functions related to the moderation of
 111 different objects in the system (objects that are submitted by
 112 end-users and need to be approved before we show them on the website).