mirror of
https://github.com/wagtail/wagtail.git
synced 2024-12-01 11:41:20 +01:00
bf0f3e02ba
Conflicts: docs/advanced_topics/api/v2/configuration.rst docs/advanced_topics/jinja2.rst docs/advanced_topics/settings.rst docs/getting_started/integrating_into_django.rst docs/getting_started/tutorial.rst docs/topics/pages.rst docs/topics/streamfield.rst gulpfile.js/config.js tox.ini wagtail/admin/tests/test_compare.py wagtail/admin/tests/test_edit_handlers.py wagtail/api/v2/signal_handlers.py wagtail/contrib/wagtailstyleguide/views.py wagtail/core/tests/test_streamfield.py wagtail/documents/tests/test_models.py wagtail/images/models.py wagtail/images/permissions.py wagtail/images/tests/test_admin_views.py wagtail/images/tests/test_image_operations.py wagtail/images/tests/test_models.py wagtail/images/tests/test_signal_handlers.py wagtail/images/views/chooser.py wagtail/images/views/images.py wagtail/images/views/multiple.py wagtail/images/wagtail_hooks.py wagtail/images/widgets.py wagtail/project_template/project_name/settings/base.py wagtail/tests/demosite/models.py wagtail/tests/non_root_urls.py wagtail/tests/settings.py wagtail/tests/testapp/migrations/0001_initial.py wagtail/tests/testapp/migrations/0008_inlinestreampage_inlinestreampagesection.py wagtail/tests/testapp/migrations/0009_defaultstreampage.py wagtail/tests/urls.py
88 lines
2.6 KiB
ReStructuredText
88 lines
2.6 KiB
ReStructuredText
.. _custom_image_model:
|
|
|
|
===================
|
|
Custom image models
|
|
===================
|
|
|
|
The ``Image`` model can be customised, allowing additional fields to be added
|
|
to images.
|
|
|
|
To do this, you need to add two models to your project:
|
|
|
|
- The image model itself that inherits from
|
|
``wagtail.images.models.AbstractImage``. This is where you would add
|
|
your additional fields
|
|
- The renditions model that inherits from
|
|
``wagtail.images.models.AbstractRendition``. This is used to store
|
|
renditions for the new model.
|
|
|
|
Here's an example:
|
|
|
|
.. code-block:: python
|
|
|
|
# models.py
|
|
from django.db import models
|
|
|
|
from wagtail.images.models import Image, AbstractImage, AbstractRendition
|
|
|
|
|
|
class CustomImage(AbstractImage):
|
|
# Add any extra fields to image here
|
|
|
|
# eg. To add a caption field:
|
|
# caption = models.CharField(max_length=255, blank=True)
|
|
|
|
admin_form_fields = Image.admin_form_fields + (
|
|
# Then add the field names here to make them appear in the form:
|
|
# 'caption',
|
|
)
|
|
|
|
|
|
class CustomRendition(AbstractRendition):
|
|
image = models.ForeignKey(CustomImage, related_name='renditions')
|
|
|
|
class Meta:
|
|
unique_together = (
|
|
('image', 'filter_spec', 'focal_point_key'),
|
|
)
|
|
|
|
|
|
.. versionchanged:: 1.10
|
|
|
|
In previous versions of Wagtail it was necessary to connect signal handlers to handle deletion of image files. As of Wagtail 1.10 this is now handled automatically.
|
|
|
|
.. note::
|
|
|
|
Fields defined on a custom image model must either be set as non-required
|
|
(``blank=True``), or specify a default value - this is because uploading
|
|
the image and entering custom data happen as two separate actions, and
|
|
Wagtail needs to be able to create an image record immediately on upload.
|
|
|
|
Then set the ``WAGTAILIMAGES_IMAGE_MODEL`` setting to point to it:
|
|
|
|
.. code-block:: python
|
|
|
|
WAGTAILIMAGES_IMAGE_MODEL = 'images.CustomImage'
|
|
|
|
|
|
.. topic:: Migrating from the builtin image model
|
|
|
|
When changing an existing site to use a custom image model, no images will
|
|
be copied to the new model automatically. Copying old images to the new
|
|
model would need to be done manually with a
|
|
`data migration <https://docs.djangoproject.com/en/1.8/topics/migrations/#data-migrations>`_.
|
|
|
|
Any templates that reference the builtin image model will still continue to
|
|
work as before but would need to be updated in order to see any new images.
|
|
|
|
.. _custom_image_model_referring_to_image_model:
|
|
|
|
Referring to the image model
|
|
============================
|
|
|
|
.. module:: wagtail.images
|
|
|
|
.. autofunction:: get_image_model
|
|
|
|
.. autofunction:: get_image_model_string
|