| 1 |
=========================== |
| 2 |
``django.contrib.humanize`` |
| 3 |
=========================== |
| 4 |
|
| 5 |
.. module:: django.contrib.humanize |
| 6 |
:synopsis: A set of Django template filters useful for adding a "human |
| 7 |
touch" to data. |
| 8 |
|
| 9 |
A set of Django template filters useful for adding a "human touch" to data. |
| 10 |
|
| 11 |
To activate these filters, add ``'django.contrib.humanize'`` to your |
| 12 |
:setting:`INSTALLED_APPS` setting. Once you've done that, use |
| 13 |
``{% load humanize %}`` in a template, and you'll have access to the following |
| 14 |
filters. |
| 15 |
|
| 16 |
.. templatefilter:: apnumber |
| 17 |
|
| 18 |
``apnumber`` |
| 19 |
============ |
| 20 |
|
| 21 |
For numbers 1-9, returns the number spelled out. Otherwise, returns the |
| 22 |
number. This follows Associated Press style. |
| 23 |
|
| 24 |
Examples: |
| 25 |
|
| 26 |
* ``1`` becomes ``one``. |
| 27 |
* ``2`` becomes ``two``. |
| 28 |
* ``10`` becomes ``10``. |
| 29 |
|
| 30 |
You can pass in either an integer or a string representation of an integer. |
| 31 |
|
| 32 |
.. templatefilter:: intcomma |
| 33 |
|
| 34 |
``intcomma`` |
| 35 |
============ |
| 36 |
|
| 37 |
Converts an integer or float (or a string representation of either) to a string |
| 38 |
containing commas every three digits. |
| 39 |
|
| 40 |
Examples: |
| 41 |
|
| 42 |
* ``4500`` becomes ``4,500``. |
| 43 |
* ``4500.2`` becomes ``4,500.2``. |
| 44 |
* ``45000`` becomes ``45,000``. |
| 45 |
* ``450000`` becomes ``450,000``. |
| 46 |
* ``4500000`` becomes ``4,500,000``. |
| 47 |
|
| 48 |
:doc:`/topics/i18n/formatting` will be respected if enabled, |
| 49 |
e.g. with the ``'de'`` language: |
| 50 |
|
| 51 |
* ``45000`` becomes ``'45.000'``. |
| 52 |
* ``450000`` becomes ``'450.000'``. |
| 53 |
|
| 54 |
.. templatefilter:: intword |
| 55 |
|
| 56 |
``intword`` |
| 57 |
=========== |
| 58 |
|
| 59 |
Converts a large integer (or a string representation of an integer) to a |
| 60 |
friendly text representation. Translates ``1.0`` as a singular phrase and all |
| 61 |
other numeric values as plural, this may be incorrect for some languages. Works |
| 62 |
best for numbers over 1 million. |
| 63 |
|
| 64 |
Examples: |
| 65 |
|
| 66 |
* ``1000000`` becomes ``1.0 million``. |
| 67 |
* ``1200000`` becomes ``1.2 million``. |
| 68 |
* ``1200000000`` becomes ``1.2 billion``. |
| 69 |
* ``-1200000000`` becomes ``-1.2 billion``. |
| 70 |
|
| 71 |
Values up to 10^100 (Googol) are supported. |
| 72 |
|
| 73 |
:doc:`/topics/i18n/formatting` will be respected if enabled, |
| 74 |
e.g. with the ``'de'`` language: |
| 75 |
|
| 76 |
* ``1000000`` becomes ``'1,0 Million'``. |
| 77 |
* ``1200000`` becomes ``'1,2 Millionen'``. |
| 78 |
* ``1200000000`` becomes ``'1,2 Milliarden'``. |
| 79 |
* ``-1200000000`` becomes ``'-1,2 Milliarden'``. |
| 80 |
|
| 81 |
.. templatefilter:: naturalday |
| 82 |
|
| 83 |
``naturalday`` |
| 84 |
============== |
| 85 |
|
| 86 |
For dates that are the current day or within one day, return "today", |
| 87 |
"tomorrow" or "yesterday", as appropriate. Otherwise, format the date using |
| 88 |
the passed in format string. |
| 89 |
|
| 90 |
**Argument:** Date formatting string as described in the :tfilter:`date` tag. |
| 91 |
|
| 92 |
Examples (when 'today' is 17 Feb 2007): |
| 93 |
|
| 94 |
* ``16 Feb 2007`` becomes ``yesterday``. |
| 95 |
* ``17 Feb 2007`` becomes ``today``. |
| 96 |
* ``18 Feb 2007`` becomes ``tomorrow``. |
| 97 |
* Any other day is formatted according to given argument or the |
| 98 |
:setting:`DATE_FORMAT` setting if no argument is given. |
| 99 |
|
| 100 |
.. templatefilter:: naturaltime |
| 101 |
|
| 102 |
``naturaltime`` |
| 103 |
=============== |
| 104 |
|
| 105 |
For datetime values, returns a string representing how many seconds, |
| 106 |
minutes or hours ago it was -- falling back to the :tfilter:`timesince` |
| 107 |
format if the value is more than a day old. In case the datetime value is in |
| 108 |
the future the return value will automatically use an appropriate phrase. |
| 109 |
|
| 110 |
Examples (when 'now' is 17 Feb 2007 16:30:00): |
| 111 |
|
| 112 |
* ``17 Feb 2007 16:30:00`` becomes ``now``. |
| 113 |
* ``17 Feb 2007 16:29:31`` becomes ``29 seconds ago``. |
| 114 |
* ``17 Feb 2007 16:29:00`` becomes ``a minute ago``. |
| 115 |
* ``17 Feb 2007 16:25:35`` becomes ``4 minutes ago``. |
| 116 |
* ``17 Feb 2007 15:30:29`` becomes ``59 minutes ago``. |
| 117 |
* ``17 Feb 2007 15:30:01`` becomes ``59 minutes ago``. |
| 118 |
* ``17 Feb 2007 15:30:00`` becomes ``an hour ago``. |
| 119 |
* ``17 Feb 2007 13:31:29`` becomes ``2 hours ago``. |
| 120 |
* ``16 Feb 2007 13:31:29`` becomes ``1 day, 2 hours ago``. |
| 121 |
* ``16 Feb 2007 13:30:01`` becomes ``1 day, 2 hours ago``. |
| 122 |
* ``16 Feb 2007 13:30:00`` becomes ``1 day, 3 hours ago``. |
| 123 |
* ``17 Feb 2007 16:30:30`` becomes ``30 seconds from now``. |
| 124 |
* ``17 Feb 2007 16:30:29`` becomes ``29 seconds from now``. |
| 125 |
* ``17 Feb 2007 16:31:00`` becomes ``a minute from now``. |
| 126 |
* ``17 Feb 2007 16:34:35`` becomes ``4 minutes from now``. |
| 127 |
* ``17 Feb 2007 17:30:29`` becomes ``an hour from now``. |
| 128 |
* ``17 Feb 2007 18:31:29`` becomes ``2 hours from now``. |
| 129 |
* ``18 Feb 2007 16:31:29`` becomes ``1 day from now``. |
| 130 |
* ``26 Feb 2007 18:31:29`` becomes ``1 week, 2 days from now``. |
| 131 |
|
| 132 |
.. templatefilter:: ordinal |
| 133 |
|
| 134 |
``ordinal`` |
| 135 |
=========== |
| 136 |
|
| 137 |
Converts an integer to its ordinal as a string. |
| 138 |
|
| 139 |
Examples: |
| 140 |
|
| 141 |
* ``1`` becomes ``1st``. |
| 142 |
* ``2`` becomes ``2nd``. |
| 143 |
* ``3`` becomes ``3rd``. |
| 144 |
|
| 145 |
You can pass in either an integer or a string representation of an integer. |
| 146 |
Negative integers are returned unchanged. |