Tweak pre/post save hooks. Return instance in .update().

1 files changed, 18 insertions, 8 deletions

diff --git a/docs/topics/3.0-announcement.md b/docs/topics/3.0-announcement.md
index 4a781503..89817ea5 100644
--- a/docs/topics/3.0-announcement.md
+++ b/docs/topics/3.0-announcement.md
@@ -116,11 +116,12 @@ This would now be split out into two separate methods.
         instance.language = validated_data.get('language', instance.language)
         instance.style = validated_data.get('style', instance.style)
         instance.save()
+        return instance
 
 	def create(self, validated_data):
         return Snippet.objects.create(**validated_data)
 
-Note that the `.create` method should return the newly created object instance.
+Note that these methods should return the newly created object instance.
 
 #### Use `.validated_data` instead of `.object`.
 
@@ -592,18 +593,27 @@ The `UniqueTogetherValidator` should be applied to a serializer, and takes a `qu
 
 The view logic for the default method handlers has been significantly simplified, due to the new serializers API.
 
-#### Removal of pre/post save hooks. 
+#### Changes to pre/post save hooks. 
 
-The following method hooks no longer exist on the new, simplified, generic views: `pre_save`, `post_save`, `pre_delete`, `post_delete`.
+The `pre_save` and `post_save` hooks no longer exist, but are replaced with `perform_create(self, serializer)` and `perform_update(self, serializer)`.
 
-If you do need custom behavior, you might choose to instead override the `.save()` method on your serializer class. For example:
+These method should save the object instance by calling `serializer.save()`, adding in any explicit additional arguments as required. They may also perform any custom pre-save or post-save behavior.
 
-    def save(self, *args, **kwargs):
-        instance = super(MySerializer).save(*args, **kwarg)
+For example:
+
+    def perform_create(self, serializer):
+        # Include the owner attribute directly, rather than from request data.
+        instance = serializer.save(owner=self.request.user)
+        # Perform a custom post-save action.
         send_email(instance.to_email, instance.message)
-		return instance
 
-Alternatively write your view logic exlpicitly, or tie your pre/post save behavior into the model class or model manager.
+The `pre_delete` and `post_delete` hooks no longer exist, and are replaced with `.perform_destroy(self, instance)`, which should delete the instance and perform any custom actions.
+
+    def perform_destroy(self, instance):
+        # Perform a custom pre-delete action.
+        send_deletion_alert(user=instance.created_by, deleted=instance)
+        # Delete the object instance.
+        instance.delete()
 
 #### Removal of view attributes.