Skip to content

Commit 22829d1

Browse files
committed
Improve polymorphism documentation
1 parent fddb06b commit 22829d1

File tree

1 file changed

+37
-1
lines changed

1 file changed

+37
-1
lines changed

docs/usage.md

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -425,7 +425,9 @@ field_name_mapping = {
425425

426426
### Working with polymorphic resources
427427

428-
This package can defer the resolution of the type of polymorphic models instances to get the appropriate type.
428+
#### Extraction of the polymorphic type
429+
430+
This package can defer the resolution of the type of polymorphic models instances to retrieve the appropriate type.
429431
However, most models are not polymorphic and for performance reasons this is only done if the underlying model is a subclass of a polymorphic model.
430432

431433
Polymorphic ancestors must be defined on settings like this:
@@ -436,6 +438,40 @@ JSON_API_POLYMORPHIC_ANCESTORS = (
436438
)
437439
```
438440

441+
#### Writing polymorphic resources
442+
443+
A polymorphic endpoint can be setup if associated with a polymorphic serializer.
444+
A polymorphic serializer take care of (de)serializing the correct instances types and can be defined like this:
445+
446+
```python
447+
class ProjectSerializer(serializers.PolymorphicModelSerializer):
448+
polymorphic_serializers = [ArtProjectSerializer, ResearchProjectSerializer]
449+
450+
class Meta:
451+
model = models.Project
452+
```
453+
454+
It must inherit from `serializers.PolymorphicModelSerializer` and define the `polymorphic_serializers` list.
455+
This attribute defines the accepted resource types.
456+
457+
458+
Polymorphic relations can also be handled with `relations.PolymorphicResourceRelatedField` like this:
459+
460+
```python
461+
class CompanySerializer(serializers.ModelSerializer):
462+
current_project = relations.PolymorphicResourceRelatedField(
463+
ProjectSerializer, queryset=models.Project.objects.all())
464+
future_projects = relations.PolymorphicResourceRelatedField(
465+
ProjectSerializer, queryset=models.Project.objects.all(), many=True)
466+
467+
class Meta:
468+
model = models.Company
469+
```
470+
471+
They must be explicitely declared with the `polymorphic_serializer` (first positional argument) correctly defined.
472+
It must be a subclass of `serializers.PolymorphicModelSerializer`.
473+
474+
439475
### Meta
440476

441477
You may add metadata to the rendered json in two different ways: `meta_fields` and `get_root_meta`.

0 commit comments

Comments
 (0)