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`_.
  27
  28 .. _Tutorial 2: ../tutorial02/
  29
  30 Requires the auth_ and contenttypes_ contrib packages to be installed.
  31
  32 auth
  33 ====
  34
  35 Django's authentication framework.
  36
  37 See the `authentication documentation`_.
  38
  39 .. _authentication documentation: ../authentication/
  40
  41 comments
  42 ========
  43
  44 A simple yet flexible comments system. This is not yet documented.
  45
  46 contenttypes
  47 ============
  48
  49 A light framework for hooking into "types" of content, where each installed
  50 Django model is a separate content type. This is not yet documented.
  51
  52 csrf
  53 ====
  54
  55 A middleware for preventing Cross Site Request Forgeries
  56
  57 See the `csrf documentation`_.
  58
  59 .. _csrf documentation: ../csrf/
  60
  61 formtools
  62 =========
  63
  64 A set of high-level abstractions for Django forms (django.newforms).
  65
  66 django.contrib.formtools.preview
  67 --------------------------------
  68
  69 An abstraction of the following workflow:
  70
  71 "Display an HTML form, force a preview, then do something with the submission."
  72
  73 Full documentation for this feature does not yet exist, but you can read the
  74 code and docstrings in ``django/contrib/formtools/preview.py`` for a start.
  75
  76 humanize
  77 ========
  78
  79 A set of Django template filters useful for adding a "human touch" to data.
  80 To activate these filters, add ``'django.contrib.humanize'`` to your
  81 ``INSTALLED_APPS`` setting. Once you've done that, use ``{% load humanize %}``
  82 in a template, and you'll have access to these filters:
  83
  84 apnumber
  85 --------
  86
  87 For numbers 1-9, returns the number spelled out. Otherwise, returns the
  88 number. This follows Associated Press style.
  89
  90 Examples:
  91
  92     * ``1`` becomes ``'one'``.
  93     * ``2`` becomes ``'two'``.
  94     * ``10`` becomes ``10``.
  95
  96 You can pass in either an integer or a string representation of an integer.
  97
  98 intcomma
  99 --------
 100
 101 Converts an integer to a string containing commas every three digits.
 102
 103 Examples:
 104
 105     * ``4500`` becomes ``'4,500'``.
 106     * ``45000`` becomes ``'45,000'``.
 107     * ``450000`` becomes ``'450,000'``.
 108     * ``4500000`` becomes ``'4,500,000'``.
 109
 110 You can pass in either an integer or a string representation of an integer.
 111
 112 intword
 113 -------
 114
 115 Converts a large integer to a friendly text representation. Works best for
 116 numbers over 1 million.
 117
 118 Examples:
 119
 120     * ``1000000`` becomes ``'1.0 million'``.
 121     * ``1200000`` becomes ``'1.2 million'``.
 122     * ``1200000000`` becomes ``'1.2 billion'``.
 123
 124 Values up to 1000000000000000 (one quadrillion) are supported.
 125
 126 You can pass in either an integer or a string representation of an integer.
 127
 128 ordinal
 129 -------
 130
 131 Converts an integer to its ordinal as a string.
 132
 133 Examples:
 134
 135     * ``1`` becomes ``'1st'``.
 136     * ``2`` becomes ``'2nd'``.
 137     * ``3`` becomes ``'3rd'``.
 138
 139 You can pass in either an integer or a string representation of an integer.
 140
 141 flatpages
 142 =========
 143
 144 A framework for managing simple "flat" HTML content in a database.
 145
 146 See the `flatpages documentation`_.
 147
 148 .. _flatpages documentation: ../flatpages/
 149
 150 Requires the sites_ contrib package to be installed as well.
 151
 152 localflavor
 153 ===========
 154
 155 A collection of various Django snippets that are useful only for a particular
 156 country or culture. For example, ``django.contrib.localflavor.usa.forms``
 157 contains a ``USZipCodeField`` that you can use to validate U.S. zip codes.
 158
 159 markup
 160 ======
 161
 162 A collection of template filters that implement common markup languages:
 163
 164     * ``textile`` -- implements `Textile`_
 165     * ``markdown`` -- implements `Markdown`_
 166     * ``restructuredtext`` -- implements `ReST (ReStructured Text)`_
 167
 168 In each case, the filter expects formatted markup as a string and returns a
 169 string representing the marked-up text. For example, the ``textile`` filter
 170 converts text that is marked-up in Textile format to HTML.
 171
 172 To activate these filters, add ``'django.contrib.markup'`` to your
 173 ``INSTALLED_APPS`` setting. Once you've done that, use ``{% load markup %}`` in
 174 a template, and you'll have access to these filters. For more documentation,
 175 read the source code in django/contrib/markup/templatetags/markup.py.
 176
 177 .. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29
 178 .. _Markdown: http://en.wikipedia.org/wiki/Markdown
 179 .. _ReST (ReStructured Text): http://en.wikipedia.org/wiki/ReStructuredText
 180
 181 redirects
 182 =========
 183
 184 A framework for managing redirects.
 185
 186 See the `redirects documentation`_.
 187
 188 .. _redirects documentation: ../redirects/
 189
 190 sites
 191 =====
 192
 193 A light framework that lets you operate multiple Web sites off of the same
 194 database and Django installation. It gives you hooks for associating objects to
 195 one or more sites.
 196
 197 See the `sites documentation`_.
 198
 199 .. _sites documentation: ../sites/
 200
 201 sitemaps
 202 ========
 203
 204 A framework for generating Google sitemap XML files.
 205
 206 See the `sitemaps documentation`_.
 207
 208 .. _sitemaps documentation: ../sitemaps/
 209
 210 syndication
 211 ===========
 212
 213 A framework for generating syndication feeds, in RSS and Atom, quite easily.
 214
 215 See the `syndication documentation`_.
 216
 217 .. _syndication documentation: ../syndication/
 218
 219 Other add-ons
 220 =============
 221
 222 If you have an idea for functionality to include in ``contrib``, let us know!
 223 Code it up, and post it to the `django-users mailing list`_.
 224
 225 .. _django-users mailing list: http://groups.google.com/group/django-users