From 7815811fe3047b5110e6993ecd72349f6f232232 Mon Sep 17 00:00:00 2001 From: Mark Aaron Shirley Date: Sun, 14 Jul 2013 18:13:37 -0700 Subject: [PATCH] Update nested serialization docs --- docs/api-guide/relations.md | 2 -- docs/api-guide/serializers.md | 17 ++++++++++------- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md index 50c9bc546..21942eeff 100644 --- a/docs/api-guide/relations.md +++ b/docs/api-guide/relations.md @@ -213,8 +213,6 @@ Nested relationships can be expressed by using serializers as fields. If the field is used to represent a to-many relationship, you should add the `many=True` flag to the serializer field. -Note that nested relationships are currently read-only. For read-write relationships, you should use a flat relational style. - ## Example For example, the following serializer: diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index d9c23580c..23c999429 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -177,7 +177,7 @@ If a nested representation may optionally accept the `None` value you should pas content = serializers.CharField(max_length=200) created = serializers.DateTimeField() -Similarly if a nested representation should be a list of items, you should the `many=True` flag to the nested serialized. +Similarly if a nested representation should be a list of items, you should pass the `many=True` flag to the nested serialized. class CommentSerializer(serializers.Serializer): user = UserSerializer(required=False) @@ -185,11 +185,13 @@ Similarly if a nested representation should be a list of items, you should the ` content = serializers.CharField(max_length=200) created = serializers.DateTimeField() ---- +Validation of nested objects will work the same as before. Errors with nested objects will be nested under the field name of the nested object. -**Note**: Nested serializers are only suitable for read-only representations, as there are cases where they would have ambiguous or non-obvious behavior if used when updating instances. For read-write representations you should always use a flat representation, by using one of the `RelatedField` subclasses. - ---- + serializer = CommentSerializer(comment, data={'user': {'email': 'foobar', 'user': 'doe'}, 'content': 'baz'}) + serializer.is_valid() + # False + serializer.errors + # {'user': {'email': [u'Enter a valid e-mail address.']}, 'created': [u'This field is required.']} ## Dealing with multiple objects @@ -293,8 +295,7 @@ You can provide arbitrary additional context by passing a `context` argument whe The context dictionary can be used within any serializer field logic, such as a custom `.to_native()` method, by accessing the `self.context` attribute. ---- - +- # ModelSerializer Often you'll want serializer classes that map closely to model definitions. @@ -331,6 +332,8 @@ The default `ModelSerializer` uses primary keys for relationships, but you can a The `depth` option should be set to an integer value that indicates the depth of relationships that should be traversed before reverting to a flat representation. +If you want to customize the way the serialization is done (e.g. using `allow_add_remove`) you'll need to define the field yourself. + ## Specifying which fields should be read-only You may wish to specify multiple fields as read-only. Instead of adding each field explicitly with the `read_only=True` attribute, you may use the `read_only_fields` Meta option, like so: