docs/add_ons.txt

   1 ============================
   2 The "django.contrib" add-ons
   3 ============================
   4
   5 Django aims to follow Python's `"batteries included" philosophy`_. It ships
   6 with a variety of extra, optional tools that solve common Web-development
   7 problems.
   8
   9 This code lives in ``django/contrib`` in the Django distribution. This document
  10 gives a rundown of the packages in ``contrib``, along with any dependencies
  11 those packages have.
  12
  13 .. admonition:: Note
  14
  15     For most of these add-ons -- specifically, the add-ons that include either
  16     models or template tags -- you'll need to add the package name (e.g.,
  17     ``'django.contrib.admin'``) to your ``INSTALLED_APPS`` setting and re-run
  18     ``manage.py syncdb``.
  19
  20 .. _"batteries included" philosophy: http://docs.python.org/tut/node12.html#batteries-included
  21
  22 admin
  23 =====
  24
  25 The automatic Django administrative interface. For more information, see
  26 `Tutorial 2`_ and the `admin documentation`_.
  27
  28 .. _Tutorial 2: ../tutorial02/
  29 .. _admin documentation: ../admin/
  30
  31 Requires the auth_ and contenttypes_ contrib packages to be installed.
  32
  33 auth
  34 ====
  35
  36 Django's authentication framework.
  37
  38 See the `authentication documentation`_.
  39
  40 .. _authentication documentation: ../authentication/
  41
  42 comments
  43 ========
  44
  45 A simple yet flexible comments system. This is not yet documented.
  46
  47 contenttypes
  48 ============
  49
  50 A light framework for hooking into "types" of content, where each installed
  51 Django model is a separate content type.
  52
  53 See the `contenttypes documentation`_.
  54
  55 .. _contenttypes documentation: ../contenttypes/
  56
  57 csrf
  58 ====
  59
  60 A middleware for preventing Cross Site Request Forgeries
  61
  62 See the `csrf documentation`_.
  63
  64 .. _csrf documentation: ../csrf/
  65
  66 flatpages
  67 =========
  68
  69 A framework for managing simple "flat" HTML content in a database.
  70
  71 See the `flatpages documentation`_.
  72
  73 .. _flatpages documentation: ../flatpages/
  74
  75 Requires the sites_ contrib package to be installed as well.
  76
  77 formtools
  78 =========
  79
  80 A set of high-level abstractions for Django forms (django.forms).
  81
  82 django.contrib.formtools.preview
  83 --------------------------------
  84
  85 An abstraction of the following workflow:
  86
  87 "Display an HTML form, force a preview, then do something with the submission."
  88
  89 See the `form preview documentation`_.
  90
  91 .. _form preview documentation: ../form_preview/
  92
  93 humanize
  94 ========
  95
  96 A set of Django template filters useful for adding a "human touch" to data.
  97 To activate these filters, add ``'django.contrib.humanize'`` to your
  98 ``INSTALLED_APPS`` setting. Once you've done that, use ``{% load humanize %}``
  99 in a template, and you'll have access to these filters:
 100
 101 apnumber
 102 --------
 103
 104 For numbers 1-9, returns the number spelled out. Otherwise, returns the
 105 number. This follows Associated Press style.
 106
 107 Examples:
 108
 109     * ``1`` becomes ``'one'``.
 110     * ``2`` becomes ``'two'``.
 111     * ``10`` becomes ``10``.
 112
 113 You can pass in either an integer or a string representation of an integer.
 114
 115 intcomma
 116 --------
 117
 118 Converts an integer to a string containing commas every three digits.
 119
 120 Examples:
 121
 122     * ``4500`` becomes ``'4,500'``.
 123     * ``45000`` becomes ``'45,000'``.
 124     * ``450000`` becomes ``'450,000'``.
 125     * ``4500000`` becomes ``'4,500,000'``.
 126
 127 You can pass in either an integer or a string representation of an integer.
 128
 129 intword
 130 -------
 131
 132 Converts a large integer to a friendly text representation. Works best for
 133 numbers over 1 million.
 134
 135 Examples:
 136
 137     * ``1000000`` becomes ``'1.0 million'``.
 138     * ``1200000`` becomes ``'1.2 million'``.
 139     * ``1200000000`` becomes ``'1.2 billion'``.
 140
 141 Values up to 1000000000000000 (one quadrillion) are supported.
 142
 143 You can pass in either an integer or a string representation of an integer.
 144
 145 ordinal
 146 -------
 147
 148 Converts an integer to its ordinal as a string.
 149
 150 Examples:
 151
 152     * ``1`` becomes ``'1st'``.
 153     * ``2`` becomes ``'2nd'``.
 154     * ``3`` becomes ``'3rd'``.
 155
 156 You can pass in either an integer or a string representation of an integer.
 157
 158 naturalday
 159 ----------
 160
 161 **New in Django development version**
 162
 163 For dates that are the current day or within one day, return "today",
 164 "tomorrow" or "yesterday", as appropriate. Otherwise, format the date using
 165 the passed in format string.
 166
 167 **Argument:** Date formatting string as described in default tag now_.
 168
 169 .. _now: ../templates/#now
 170
 171 Examples (when 'today' is 17 Feb 2007):
 172
 173     * ``16 Feb 2007`` becomes ``yesterday``.
 174     * ``17 Feb 2007`` becomes ``today``.
 175     * ``18 Feb 2007`` becomes ``tomorrow``.
 176     * Any other day is formatted according to given argument or the
 177       `DATE_FORMAT`_ setting if no argument is given.
 178
 179 .. _DATE_FORMAT: ../settings/#date_format
 180
 181 localflavor
 182 ===========
 183
 184 A collection of various Django snippets that are useful only for a particular
 185 country or culture. For example, ``django.contrib.localflavor.us.forms``
 186 contains a ``USZipCodeField`` that you can use to validate U.S. zip codes.
 187
 188 See the `localflavor documentation`_.
 189
 190 .. _localflavor documentation: ../localflavor/
 191
 192 markup
 193 ======
 194
 195 A collection of template filters that implement common markup languages:
 196
 197     * ``textile`` -- implements `Textile`_
 198     * ``markdown`` -- implements `Markdown`_
 199     * ``restructuredtext`` -- implements `ReST (ReStructured Text)`_
 200
 201 In each case, the filter expects formatted markup as a string and returns a
 202 string representing the marked-up text. For example, the ``textile`` filter
 203 converts text that is marked-up in Textile format to HTML.
 204
 205 To activate these filters, add ``'django.contrib.markup'`` to your
 206 ``INSTALLED_APPS`` setting. Once you've done that, use ``{% load markup %}`` in
 207 a template, and you'll have access to these filters. For more documentation,
 208 read the source code in django/contrib/markup/templatetags/markup.py.
 209
 210 .. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29
 211 .. _Markdown: http://en.wikipedia.org/wiki/Markdown
 212 .. _ReST (ReStructured Text): http://en.wikipedia.org/wiki/ReStructuredText
 213
 214 redirects
 215 =========
 216
 217 A framework for managing redirects.
 218
 219 See the `redirects documentation`_.
 220
 221 .. _redirects documentation: ../redirects/
 222
 223 sessions
 224 ========
 225
 226 A framework for storing data in anonymous sessions.
 227
 228 See the `sessions documentation`_.
 229
 230 .. _sessions documentation: ../sessions/
 231
 232 sites
 233 =====
 234
 235 A light framework that lets you operate multiple Web sites off of the same
 236 database and Django installation. It gives you hooks for associating objects to
 237 one or more sites.
 238
 239 See the `sites documentation`_.
 240
 241 .. _sites documentation: ../sites/
 242
 243 sitemaps
 244 ========
 245
 246 A framework for generating Google sitemap XML files.
 247
 248 See the `sitemaps documentation`_.
 249
 250 .. _sitemaps documentation: ../sitemaps/
 251
 252 syndication
 253 ===========
 254
 255 A framework for generating syndication feeds, in RSS and Atom, quite easily.
 256
 257 See the `syndication documentation`_.
 258
 259 .. _syndication documentation: ../syndication_feeds/
 260
 261 webdesign
 262 =========
 263
 264 Helpers and utilities targeted primarily at Web *designers* rather than
 265 Web *developers*.
 266
 267 See the `Web design helpers documentation`_.
 268
 269 .. _Web design helpers documentation: ../webdesign/
 270
 271 Other add-ons
 272 =============
 273
 274 If you have an idea for functionality to include in ``contrib``, let us know!
 275 Code it up, and post it to the `django-users mailing list`_.
 276
 277 .. _django-users mailing list: http://groups.google.com/group/django-users