Added documentation for get_upload_to function in AbstractImage and AbstractRendition class

- Builds on previous PR #8228
- Fixes #2601

CHANGELOG.txt

@@ -106,6 +106,7 @@ Changelog
  * Docs: Add `Page` model reference `get_children` documentation (Salvo Polizzi)
  * Docs: Enforce CI build checks for documentation so that malformed links or missing images will not be allowed (Neeraj Yetheendran)
  * Docs: Update spelling on customizing admin template and page model section from British to American English (Victoria Poromon)
+ * Docs: Add documentation for how to override the file locations for custom image models via `get_upload_to` methods (Osaf AliSayed, Dharmik Gangani)
  * Maintenance: Update BeautifulSoup upper bound to 4.12.x (scott-8)
  * Maintenance: Migrate initialization of classes (such as `body.ready`) from multiple JavaScript implementations to one Stimulus controller `w-init` (Chiemezuo Akujobi)
  * Maintenance: Adopt the usage of translate string literals using `arg=_('...')` in all `wagtailadmin` module templates (Chiemezuo Akujobi)

CONTRIBUTORS.md

@@ -788,6 +788,7 @@
 * Sankalp
 * V Rohitansh
 * Andreas Donig
+* Osaf AliSayed
 
 ## Translators
 

docs/advanced_topics/images/custom_image_model.md

@@ -67,3 +67,26 @@ work as before but would need to be updated in order to see any new images.
 
 .. autofunction:: get_image_model_string
 ```
+
+(custom_image_model_upload_location)=
+
+## Overriding the upload location
+
+The following methods can be overridden on your custom `Image` or `Rendition` models to customize how the original and rendition image files get stored.
+
+```{eval-rst}
+.. automodule:: wagtail.images.models
+    :noindex:
+
+.. class:: AbstractImage
+    :noindex:
+
+    .. automethod:: get_upload_to
+
+.. class:: AbstractRendition
+    :noindex:
+
+    .. automethod:: get_upload_to
+```
+
+Refer to the Django [`FileField.upload_to`](https://docs.djangoproject.com/en/stable/ref/models/fields/#django.db.models.FileField.upload_to) function to further understand how the function works.

docs/releases/6.0.md

@@ -146,6 +146,7 @@ This feature was implemented by Nick Lee, Thibaud Colas, and Sage Abdullah.
  * Add `Page` model reference `get_children` documentation (Salvo Polizzi)
  * Enforce CI build checks for documentation so that malformed links or missing images will not be allowed (Neeraj Yetheendran)
  * Update spelling on customizing admin template and page model section from British to American English (Victoria Poromon)
+ * Add documentation for how to override the file locations for custom image models [](custom_image_model_upload_location) (Osaf AliSayed, Dharmik Gangani)
 
 ### Maintenance
 

wagtail/images/models.py

@@ -300,6 +300,11 @@ class AbstractImage(ImageFileMixin, CollectionMember, index.Indexed, models.Mode
         self.file.seek(0)
 
     def get_upload_to(self, filename):
+        """
+        Generates a file path in the "original_images" folder.
+        Ensuring ASCII characters and limiting length to prevent filesystem issues during uploads.
+        """
+
         folder_name = "original_images"
         filename = self.file.field.storage.get_valid_name(filename)
 
@@ -1264,6 +1269,9 @@ class AbstractRendition(ImageFileMixin, models.Model):
         return self.img_tag()
 
     def get_upload_to(self, filename):
+        """
+        Generates a file path within the "images" folder by combining the folder name and the validated filename.
+        """
         folder_name = "images"
         filename = self.file.field.storage.get_valid_name(filename)
         return os.path.join(folder_name, filename)