From fa59e2830fb9a605cb3e3027152fa898263d3802 Mon Sep 17 00:00:00 2001
From: Oliver Walters <oliver.henry.walters@gmail.com>
Date: Fri, 19 Jun 2026 10:13:29 +0000
Subject: [PATCH] Update examples for format_date

---
 docs/docs/report/helpers.md                   | 63 ++++++++++++++++---
 .../InvenTree/report/templatetags/report.py   |  1 +
 src/backend/InvenTree/report/test_tags.py     |  6 +-
 3 files changed, 59 insertions(+), 11 deletions(-)

diff --git a/docs/docs/report/helpers.md b/docs/docs/report/helpers.md
index abff09514e..2d414f4bc1 100644
--- a/docs/docs/report/helpers.md
+++ b/docs/docs/report/helpers.md
@@ -407,6 +407,12 @@ Common patterns:
 
 For rendering date and datetime information, the following helper functions are available:
 
+Both functions resolve their output using the following priority order:
+
+1. **`fmt=` argument** — a [strftime format string](https://docs.python.org/3/library/datetime.html#format-codes). When provided, this takes full priority and the `locale` argument is ignored.
+2. **`locale=` argument** (or the `REPORT_LOCALE` global setting) — when no `fmt` is given, Babel formats the value in a locale-aware *medium* style (e.g. `Jan 12, 2025` for `en-us`).
+3. **ISO 8601 fallback** — when neither `fmt` nor a locale is available, the value is returned in ISO format (e.g. `2025-01-12`).
+
 ### format_date
 
 ::: report.templatetags.report.format_date
@@ -414,6 +420,33 @@ For rendering date and datetime information, the following helper functions are
         show_docstring_description: false
         show_source: False
 
+#### Examples
+
+```html
+{% raw %}
+{% load report %}
+
+<!-- ISO fallback (no fmt, no locale) -->
+{% format_date my_date %}
+<!-- output: 2025-01-12 -->
+
+<!-- Explicit strftime format string — locale is ignored -->
+{% format_date my_date fmt="%d/%m/%Y" %}
+<!-- output: 12/01/2025 -->
+
+<!-- Locale-aware medium format -->
+{% format_date my_date locale='en-us' %}
+<!-- output: Jan 12, 2025 -->
+
+{% format_date my_date locale='de-de' %}
+<!-- output: 12.01.2025 -->
+
+<!-- Convert from a different timezone before formatting -->
+{% format_date my_date timezone="Australia/Sydney" locale='en-au' %}
+
+{% endraw %}
+```
+
 ### format_datetime
 
 ::: report.templatetags.report.format_datetime
@@ -421,20 +454,30 @@ For rendering date and datetime information, the following helper functions are
         show_docstring_description: false
         show_source: False
 
-### Date Formatting
-
-If not specified, these methods return a result which uses ISO formatting. Refer to the [datetime format codes](https://docs.python.org/3/library/datetime.html#format-codes) for more information! |
-
-
-### Example
-
-A simple example of using the date formatting helper functions:
+#### Examples
 
 ```html
 {% raw %}
 {% load report %}
-Date: {% format_date my_date timezone="Australia/Sydney" %}
-Datetime: {% format_datetime my_datetime format="%d-%m-%Y %H:%M%S" %}
+
+<!-- ISO fallback (no fmt, no locale) -->
+{% format_datetime my_datetime %}
+<!-- output: 2025-01-12T14:30:00+00:00 -->
+
+<!-- Explicit strftime format — locale is ignored -->
+{% format_datetime my_datetime fmt="%d-%m-%Y %H:%M" %}
+<!-- output: 12-01-2025 14:30 -->
+
+<!-- Locale-aware medium format -->
+{% format_datetime my_datetime locale='en-us' %}
+<!-- output: Jan 12, 2025, 2:30:00 PM -->
+
+{% format_datetime my_datetime locale='de-de' %}
+<!-- output: 12.01.2025, 14:30:00 -->
+
+<!-- Convert to a specific timezone before formatting -->
+{% format_datetime my_datetime timezone="Australia/Sydney" locale='en-au' %}
+
 {% endraw %}
 ```
 
diff --git a/src/backend/InvenTree/report/templatetags/report.py b/src/backend/InvenTree/report/templatetags/report.py
index 483ecf91f1..33abd3b022 100644
--- a/src/backend/InvenTree/report/templatetags/report.py
+++ b/src/backend/InvenTree/report/templatetags/report.py
@@ -1004,6 +1004,7 @@ def format_datetime(
             dt, format='medium', locale=get_locale(resolved_locale)
         )
 
+    # Final backup - return an ISO formatted string
     return dt.isoformat()
 
 
diff --git a/src/backend/InvenTree/report/test_tags.py b/src/backend/InvenTree/report/test_tags.py
index 5b2ade0362..abbbfb780e 100644
--- a/src/backend/InvenTree/report/test_tags.py
+++ b/src/backend/InvenTree/report/test_tags.py
@@ -439,6 +439,7 @@ class ReportTagTest(PartImageTestMixin, InvenTreeTestCase):
         ]
 
         for tz, fmt, expected in tests:
+            print(tz, fmt, expected)
             result = report_tags.format_datetime(time, tz, fmt)
             self.assertEqual(result, expected)
 
@@ -715,7 +716,10 @@ class ReportTagTest(PartImageTestMixin, InvenTreeTestCase):
     def test_format_date(self):
         """Test the format_date template tag."""
         dt = timezone.datetime(year=2024, month=3, day=13)
-        self.assertEqual(report_tags.format_date(dt), '2024-03-13')
+        self.assertEqual(report_tags.format_date(dt, locale='de-de'), '13.03.2024')
+        self.assertEqual(report_tags.format_date(dt, locale='en-us'), 'Mar 13, 2024')
+        self.assertEqual(report_tags.format_date(dt, locale='en-au'), '13 Mar 2024')
+        self.assertEqual(report_tags.format_date(dt, locale='fr-fr'), '13 mars 2024')
         self.assertEqual(report_tags.format_date(dt, fmt='%d-%m-%y'), '13-03-24')
 
         # Test with an invalid date