Apply Aldryn Reversion support

Using Aldryn Reversion in your project is fairly strightforward.

There are two key steps required:

  • applying a registration decorator to your model
  • adding a mixin to the model’s admin class definition

Model registration

For the model, add @version_controlled_content as a decorator:

from aldryn-reversion.core import version_controlled_content

@version_controlled_content
class MyModel(models.Model):
    ...

If your model has foreign key relations, use the follow property from django-reversions when applying the decorator:

@version_controlled_content(follow=['my_fk_field'])
class MyModel(models.Model):
    my_fk_field = models.ForeignKey(OtherModel)
    ...

This also adds the related objects as version-controlled content.

Note

These related models should also be registered with django-reversion in their own right.

Options

If you need more control over exactly what is versioned, then use @reversion.register() rather than the @version-controlled-content decorator.

follow_placeholders

By default, a model’s Placeholder fields are versioned (in case of using @version-controlled-content decorator). Setting follow_placeholders to False disables this behaviour. In this case changes to plugins inside this placeholder fields are not revisioned but if we change the placeholder object this field points to, that change will be picked up by reversion.

Pass this option when registering the model with reversion:

@reversion.register(
    adapter_cls=ContentEnabledVersionAdapter,
    follow_placeholders=False,
    revision_manager=reversion.default_revision_manager,
)
class MyModel(models.Model):
    ...
    placeholder = PlaceholderField()

follow

If your model has foreign key relations, whose destination objects you also want versioned, use the follow property from django-reversions when applying the decorator:

@version_controlled_content(follow=['my_fk_relation', 'other_fk_relation'])
class MyModel(models.Model):
    ...
    my_fk_relation = models.ForeignKey(OtherModel)
    other_fk_relation = models.ForeignKey(OtherModel)

Other options

You should be able to also use other django-reversion options that are available for revision.register as described in Advanced model registration

Admin registration

For the admin, replace PlaceholderAdminMixin with VersionedPlaceholderAdminMixin in the ModelAdmin class for any models that include Placeholders that need to be versioned:

from aldryn-reversion.admin import VersionedPlacholderAdminMixin

class MyModelAdmin(VersionedPlacholderAdminMixin, admin.ModelAdmin):
    ...

Revisions are accessible from the model’s admin change form.

Important

In restoring a revision you will also restore all objects that belong to that revision to the state in which they were saved with that revision. This behaviour may not be expected by end-users.

Deleted objects

If an object has been deleted, its admin change form will obviously no longer be available.

However, the model’s admin change list view offers a Recover view, that allows you to restore a deleted object along with the translations that belong to it.

If foreign key relations have been registered with the follow property and they are required for this object, they too will be restored automatically, to the state captured in the relevant revision.