From 83f762e3ac8a531eec0886d0f10d38c86dcde715 Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Fri, 8 Oct 2010 15:43:20 +0000 Subject: [PATCH] Fixed #13188 -- Moved date format documentation from the now template tag to the date filter. Thanks, dwillis and timo. Backport from trunk (r14013). git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@14021 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/templates/builtins.txt | 159 ++++++++++++++++---------------- 1 file changed, 81 insertions(+), 78 deletions(-) diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index a20ab170c0..ff6d88f38f 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -644,75 +644,12 @@ See :doc:`Custom tag and filter libraries ` for mor now ~~~ -Display the date, formatted according to the given string. +Display the current date and/or time, according to the given string. -Uses the same format as PHP's ``date()`` function (http://php.net/date) -with some custom extensions. - -Available format strings: - - ================ ======================================== ===================== - Format character Description Example output - ================ ======================================== ===================== - a ``'a.m.'`` or ``'p.m.'`` (Note that ``'a.m.'`` - this is slightly different than PHP's - output, because this includes periods - to match Associated Press style.) - A ``'AM'`` or ``'PM'``. ``'AM'`` - b Month, textual, 3 letters, lowercase. ``'jan'`` - B Not implemented. - c ISO 8601 Format. ``2008-01-02T10:30:00.000123`` - d Day of the month, 2 digits with ``'01'`` to ``'31'`` - leading zeros. - D Day of the week, textual, 3 letters. ``'Fri'`` - f Time, in 12-hour hours and minutes, ``'1'``, ``'1:30'`` - with minutes left off if they're zero. - Proprietary extension. - F Month, textual, long. ``'January'`` - g Hour, 12-hour format without leading ``'1'`` to ``'12'`` - zeros. - G Hour, 24-hour format without leading ``'0'`` to ``'23'`` - zeros. - h Hour, 12-hour format. ``'01'`` to ``'12'`` - H Hour, 24-hour format. ``'00'`` to ``'23'`` - i Minutes. ``'00'`` to ``'59'`` - I Not implemented. - j Day of the month without leading ``'1'`` to ``'31'`` - zeros. - l Day of the week, textual, long. ``'Friday'`` - L Boolean for whether it's a leap year. ``True`` or ``False`` - m Month, 2 digits with leading zeros. ``'01'`` to ``'12'`` - M Month, textual, 3 letters. ``'Jan'`` - n Month without leading zeros. ``'1'`` to ``'12'`` - N Month abbreviation in Associated Press ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'`` - style. Proprietary extension. - O Difference to Greenwich time in hours. ``'+0200'`` - P Time, in 12-hour hours, minutes and ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'`` - 'a.m.'/'p.m.', with minutes left off - if they're zero and the special-case - strings 'midnight' and 'noon' if - appropriate. Proprietary extension. - r RFC 2822 formatted date. ``'Thu, 21 Dec 2000 16:01:07 +0200'`` - s Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'`` - S English ordinal suffix for day of the ``'st'``, ``'nd'``, ``'rd'`` or ``'th'`` - month, 2 characters. - t Number of days in the given month. ``28`` to ``31`` - T Time zone of this machine. ``'EST'``, ``'MDT'`` - u Microseconds. ``0`` to ``999999`` - U Seconds since the Unix Epoch - (January 1 1970 00:00:00 UTC). - w Day of the week, digits without ``'0'`` (Sunday) to ``'6'`` (Saturday) - leading zeros. - W ISO-8601 week number of year, with ``1``, ``53`` - weeks starting on Monday. - y Year, 2 digits. ``'99'`` - Y Year, 4 digits. ``'1999'`` - z Day of the year. ``0`` to ``365`` - Z Time zone offset in seconds. The ``-43200`` to ``43200`` - offset for timezones west of UTC is - always negative, and for those east of - UTC is always positive. - ================ ======================================== ===================== +Given format can be one of the predefined ones ``DATE_FORMAT``, +``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``, +or a custom format, same as the :tfilter:`date` filter. Note that predefined +formats may vary depending on the current locale. Example:: @@ -727,10 +664,6 @@ escaped, because it's not a format character:: This would display as "It is the 4th of September". -.. versionadded:: 1.2 - -The ``c`` and ``u`` format specification characters were added in Django 1.2. - .. templatetag:: regroup regroup @@ -1138,10 +1071,77 @@ date Formats a date according to the given format. -Given format can be one of the predefined ones ``DATE_FORMAT``, -``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``, -or a custom format, same as the :ttag:`now` tag. Note that predefined formats -may vary depending on the current locale. +Uses the same format as PHP's ``date()`` function (http://php.net/date) +with some custom extensions. + +Available format strings: + + ================ ======================================== ===================== + Format character Description Example output + ================ ======================================== ===================== + a ``'a.m.'`` or ``'p.m.'`` (Note that ``'a.m.'`` + this is slightly different than PHP's + output, because this includes periods + to match Associated Press style.) + A ``'AM'`` or ``'PM'``. ``'AM'`` + b Month, textual, 3 letters, lowercase. ``'jan'`` + B Not implemented. + c ISO 8601 Format. ``2008-01-02T10:30:00.000123`` + d Day of the month, 2 digits with ``'01'`` to ``'31'`` + leading zeros. + D Day of the week, textual, 3 letters. ``'Fri'`` + f Time, in 12-hour hours and minutes, ``'1'``, ``'1:30'`` + with minutes left off if they're zero. + Proprietary extension. + F Month, textual, long. ``'January'`` + g Hour, 12-hour format without leading ``'1'`` to ``'12'`` + zeros. + G Hour, 24-hour format without leading ``'0'`` to ``'23'`` + zeros. + h Hour, 12-hour format. ``'01'`` to ``'12'`` + H Hour, 24-hour format. ``'00'`` to ``'23'`` + i Minutes. ``'00'`` to ``'59'`` + I Not implemented. + j Day of the month without leading ``'1'`` to ``'31'`` + zeros. + l Day of the week, textual, long. ``'Friday'`` + L Boolean for whether it's a leap year. ``True`` or ``False`` + m Month, 2 digits with leading zeros. ``'01'`` to ``'12'`` + M Month, textual, 3 letters. ``'Jan'`` + n Month without leading zeros. ``'1'`` to ``'12'`` + N Month abbreviation in Associated Press ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'`` + style. Proprietary extension. + O Difference to Greenwich time in hours. ``'+0200'`` + P Time, in 12-hour hours, minutes and ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'`` + 'a.m.'/'p.m.', with minutes left off + if they're zero and the special-case + strings 'midnight' and 'noon' if + appropriate. Proprietary extension. + r RFC 2822 formatted date. ``'Thu, 21 Dec 2000 16:01:07 +0200'`` + s Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'`` + S English ordinal suffix for day of the ``'st'``, ``'nd'``, ``'rd'`` or ``'th'`` + month, 2 characters. + t Number of days in the given month. ``28`` to ``31`` + T Time zone of this machine. ``'EST'``, ``'MDT'`` + u Microseconds. ``0`` to ``999999`` + U Seconds since the Unix Epoch + (January 1 1970 00:00:00 UTC). + w Day of the week, digits without ``'0'`` (Sunday) to ``'6'`` (Saturday) + leading zeros. + W ISO-8601 week number of year, with ``1``, ``53`` + weeks starting on Monday. + y Year, 2 digits. ``'99'`` + Y Year, 4 digits. ``'1999'`` + z Day of the year. ``0`` to ``365`` + Z Time zone offset in seconds. The ``-43200`` to ``43200`` + offset for timezones west of UTC is + always negative, and for those east of + UTC is always positive. + ================ ======================================== ===================== + +.. versionadded:: 1.2 + +The ``c`` and ``u`` format specification characters were added in Django 1.2. For example:: @@ -1151,7 +1151,10 @@ If ``value`` is a ``datetime`` object (e.g., the result of ``datetime.datetime.now()``), the output will be the string ``'Wed 09 Jan 2008'``. -Another example: +Given format can be one of the predefined ones ``DATE_FORMAT``, +``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``, +or a custom format, same as the :ttag:`now` tag. Note that predefined formats +may vary depending on the current locale. Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is, for example, ``"es"``, then for:: @@ -1788,7 +1791,7 @@ time Formats a time according to the given format. Given format can be the predefined one ``TIME_FORMAT``, or a custom format, -same as the :ttag:`now` tag. Note that the predefined format is locale- +same as the :tfilter:`date` filter. Note that the predefined format is locale- dependant. The time filter will only accept parameters in the format string that relate