diff --git a/docs/reference/pages/model_reference.md b/docs/reference/pages/model_reference.md index d548286ab4..99875b838e 100644 --- a/docs/reference/pages/model_reference.md +++ b/docs/reference/pages/model_reference.md @@ -487,6 +487,42 @@ The `locale` and `translation_key` fields have a unique key constraint to preven .. autoattribute:: localized ``` +## `RevisionMixin` + +`RevisionMixin` is an abstract model that can be added to any non-page Django model to allow saving revisions of its instances. +Pages already include this mixin, so there is no need to add it. + +```{versionadded} 4.0 +The model is added to allow Snippets to save revisions, revert to a previous revision, and compare changes between revisions. +``` + +### Database fields + +```{eval-rst} +.. class:: RevisionMixin + + .. attribute:: latest_revision + + (foreign key to :class:`~wagtail.models.Revision`) + + This points to the latest revision created for the object. This reference is stored in the database for performance optimisation. +``` + +### Methods and properties + +```{eval-rst} +.. class:: RevisionMixin + :noindex: + + .. autoattribute:: revisions + + .. automethod:: save_revision + + .. automethod:: get_latest_revision_as_object + + .. automethod:: with_content_json +``` + (revision_model_ref)= ## `Revision` diff --git a/wagtail/models/__init__.py b/wagtail/models/__init__.py index 5a52d95cd2..006c836c1d 100644 --- a/wagtail/models/__init__.py +++ b/wagtail/models/__init__.py @@ -232,12 +232,14 @@ class RevisionMixin(models.Model): @property def revisions(self): """ - Returns revisions that belong to this object. + Returns revisions that belong to the object. - Subclasses should define a GenericRelation to Revision and override - this property to return that GenericRelation. This allows subclasses - to customise the `related_query_name` of the GenericRelation and add - some custom logic (e.g. to always use the specific instance in Page). + Subclasses should define a + :class:`~django.contrib.contenttypes.fields.GenericRelation` to + :class:`~wagtail.models.Revision` and override this property to return + that ``GenericRelation``. This allows subclasses to customise the + ``related_query_name`` of the ``GenericRelation`` and add custom logic + (e.g. to always use the specific instance in ``Page``). """ return Revision.objects.filter( content_type=self.get_content_type(), @@ -263,6 +265,10 @@ class RevisionMixin(models.Model): return self.latest_revision def get_latest_revision_as_object(self): + """ + Returns the latest revision of the object as an instance of the model. + If no latest revision exists, returns the object itself. + """ latest_revision = self.get_latest_revision() if latest_revision: return latest_revision.as_object() @@ -295,7 +301,8 @@ class RevisionMixin(models.Model): * ``latest_revision`` - If ``TranslatableMixin`` is applied, the following field values are also preserved: + If :class:`~wagtail.models.TranslatableMixin` is applied, the following field values + are also preserved: * ``translation_key`` * ``locale`` @@ -331,15 +338,17 @@ class RevisionMixin(models.Model): ): """ Creates and saves a revision. - :param user: the user performing the action - :param submitted_for_moderation: indicates whether the object was submitted for moderation - :param approved_go_live_at: the date and time the revision is approved to go live - :param changed: indicates whether there were any content changes - :param log_action: flag for logging the action. Pass False to skip logging. Can be passed an action string. - Defaults to 'wagtail.edit' when no 'previous_revision' param is passed, otherwise 'wagtail.revert' - :param previous_revision: indicates a revision reversal. Should be set to the previous revision instance - :param clean: Set this to False to skip cleaning object content before saving this revision - :return: the newly created revision + + :param user: The user performing the action. + :param submitted_for_moderation: Indicates whether the object was submitted for moderation. + :param approved_go_live_at: The date and time the revision is approved to go live. + :param changed: Indicates whether there were any content changes. + :param log_action: Flag for logging the action. Pass ``False`` to skip logging. Can be passed an action string. + Defaults to ``"wagtail.edit"`` when no ``previous_revision`` param is passed, otherwise ``"wagtail.revert"``. + :param previous_revision: Indicates a revision reversal. Should be set to the previous revision instance. + :type previous_revision: Revision + :param clean: Set this to ``False`` to skip cleaning object content before saving this revision. + :return: The newly created revision. """ if clean: self.full_clean()