Using Aldryn Reversion¶
After you have set up and configured your models so that they are registered
for revision support you can start using the aldryn-reversion
end-user features.
Restoring object versions¶
Django already keeps track of changes to objects and makes their history available in the object’s
qadmin edit form. With aldryn-reversion
that history has more features.
As soon as an object is created, an Initial version is created and treated as a restore point.
For each record in an object’s history you’ll now find a link to the restore revision form.
To restore a previous object version, select the desired date, check what will be changed, and if you are satisfied with the proposed changes, confirm to restore the revision.
Note
Note that the revision will be restored as is - all objects related to the object you are restoring will also be restored to the same revision. That means that any related object that is also stored in this revision would be restored to the point at which that object was stored.
This will be applicable to entire relation tree (if follow
was configured).
Once the the object is restored its content will be set to the revision you’ve chosen and you will be redirected to the object’s edit form.
You might also want to modify some of the related objects, since they too will be affected by restoring to a previous revision.
Note
If follow was not configured properly and as a result the related
objects were not stored as part of the selected revision, you could end
up with an IntegrityError
. In such a case you will first need
to restore the related object.
Recovering deleted objects¶
Another powerful feature of aldryn-reversion
is the ability to
recover deleted objects.
This function is available on a model’s change list page - a Recover deleted option is available near the top of the page.
If there are any deleted objects which do not currently exist in the database but for which there is a version stored by reversions, they will be listed on the recovery page.
To recover a deleted object, simply choose an object, check the instructions and if there are no conflicts for the related fields select the Yes, I’m sure button.
If there are any conflicts that can be resolved by the user (the model was
registered with the aldryn-reversions
decorator and with admin mixin)
the user will be presented with a list of links for recovering the related
objects first.
Note
In current implementation only required FKs are considered as a conflicts,
but this would be changed in next versions since if relation existed for
not required FK, and related object was deleted you will end up with
IntegrityError
when you will try to restore this object.
In such cases if you know which related object is missing and if it was
registered with aldryn-reversion
for revision tracking and with admin
mixin - you can recover related object first and then return to restore
this object.
If a related object was not registered with the admin mixin but was
registered for revision tracking aldryn-reversion
will attempt to resolve
the conflict automatically by examining the required FK relations.
If automatic conflict resolution was successful you will be able to restore
the object and its required relations.
Note
Note that automatic conflict resolution will try to use the selected object revision. Related objects will be restored to the version at which they were in that revision - not the object’s latest version. Be sure to examine the related objects carefully and edit them so that they are in the desired state.
Translations (django-parler)¶
When a model that is registered with aldryn-reversion
contains translatable
fields, recover form will also have the option to select translations
to restore.
In that case at least one translation should be selected.
CMS placeholder field¶
If a model has placeholder
fields and aldryn-reversion
was not
configured to ignore those fields, they will also be tracked as part of
object’s revision.
In such cases, when the placeholder object representing the parent model’s placeholder field is deleted, you will be notified and it will be restored as part of the recovery process.
Note
If only the placeholder object is deleted (and not the plugins that it holds) you will be able to restore both the placeholder and the plugins - in most cases the plugins will not have changed. If, on the other hand, both the placeholder and the related plugins were deleted, the result would be an empty placeholder. You may still be able to restore the plugins if, after recovering the deleted object, you restore an object version which contains the plugins.
When reverting history, the object will be restored to the corresponding revision automatically, so it may be a good idea to check the restored object and its plugins and edit them where necessary.