From 39faf6f98005cec0b2f4d6fdf4d3f89bda3560d8 Mon Sep 17 00:00:00 2001 From: Gil Forcada Codinachs Date: Mon, 2 Feb 2026 10:09:35 +0100 Subject: [PATCH 1/4] docs: explain how to customize a serializer --- docs/source/usage/customization.md | 89 ++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/docs/source/usage/customization.md b/docs/source/usage/customization.md index 0125b9367b..73ce0b35d6 100644 --- a/docs/source/usage/customization.md +++ b/docs/source/usage/customization.md @@ -62,3 +62,92 @@ It is recommended to pass all values through `json_compatible` in order to valid For customizing a specific field instance, a named `IFieldSerializer` adapter can be registered. The name may either be the full dotted name of the field, such as `plone.app.dexterity.behaviors.exclfromnav.IExcludeFromNavigation.exclude_from_nav`, or the shortname of the field, such as `exclude_from_nav`. + + +### Dexterity content types + +The API automatically provides a default serialization for all Dexterity content types. + +If you look to customize the serialization of a given content type, please do the following. + +Define a custom adapter: + +```xml + +``` + +```python +from plone import api +from plone.restapi.serializer.dxcontent import SerializeToJson + + +class MySerializer(SerializeToJson): + + def __call__(self, version=None, include_items=True, include_expansion=True): + # default provided by Plone + result = super().__call__( + version=version, + include_items=include_items, + include_expansion=include_expansion, + ) + # + # here goes your custom logic + # + return result +``` + +With these changes you will have a custom serializer for your content type. + + +```{warning} +If you modify, as shown above, the serialization of a content type, +you might also have to customize the deserialization. See below. +``` + +#### Deserialization + +The reverse of the serialization also happens for the deserialization. + +A default deserializer is provided by the API, but in case you want to customize it, you can as follows. + +Define a custom adapter: + +```xml + +``` + +```python +from plone import api +from plone.restapi.deserializer.dxcontent import DeserializeFromJson + + +class MyDeserializer(DeserializeFromJson): + + def __call__( + self, validate_all=False, data=None, create=False, mask_validation_errors=True + ): + # + # your custom logic goes here, you might want to manipulate the `data` value + # + + # after your custom logic, you might rely on the default provided by Plone + result = super().__call__( + validate_all=validate_all, + data=data, + create=create, + mask_validation_errors=mask_validation_errors, + ) + return result +``` + +With this, you will be able to manipulate the data that gets on a specific content type. From 710dcd62a7fb2fbe71d81d6ff7d175431036a8d8 Mon Sep 17 00:00:00 2001 From: Gil Forcada Codinachs Date: Wed, 4 Feb 2026 07:43:55 +0100 Subject: [PATCH 2/4] Add news entry --- news/1975.documentation | 1 + 1 file changed, 1 insertion(+) create mode 100644 news/1975.documentation diff --git a/news/1975.documentation b/news/1975.documentation new file mode 100644 index 0000000000..76208b43c2 --- /dev/null +++ b/news/1975.documentation @@ -0,0 +1 @@ +Explain how to customize serializers for content types @gforcada From b4bcace19d0cfc63db191c07f97a820d27aa8be8 Mon Sep 17 00:00:00 2001 From: David Glick Date: Thu, 19 Feb 2026 22:10:04 -0800 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Steve Piercy --- docs/source/usage/customization.md | 33 ++++++++++++++---------------- 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/docs/source/usage/customization.md b/docs/source/usage/customization.md index 73ce0b35d6..30cd855766 100644 --- a/docs/source/usage/customization.md +++ b/docs/source/usage/customization.md @@ -68,20 +68,20 @@ The name may either be the full dotted name of the field, such as `plone.app.dex The API automatically provides a default serialization for all Dexterity content types. -If you look to customize the serialization of a given content type, please do the following. +To customize the serialization of a given content type, define a custom adapter as shown. -Define a custom adapter: - -```xml +```{code-block} xml +:caption: configure.zcml ``` -```python +```{code-block} python +:caption: serializers.py from plone import api from plone.restapi.serializer.dxcontent import SerializeToJson @@ -101,32 +101,30 @@ class MySerializer(SerializeToJson): return result ``` -With these changes you will have a custom serializer for your content type. - ```{warning} -If you modify, as shown above, the serialization of a content type, -you might also have to customize the deserialization. See below. +If you modify the serialization of a content type, you might need to customize its deserialization as described in the next section. ``` #### Deserialization -The reverse of the serialization also happens for the deserialization. +The reverse of serialization is deserialization. -A default deserializer is provided by the API, but in case you want to customize it, you can as follows. +The API provides a default deserializer. +You can customize it with an adapter as shown. -Define a custom adapter: - -```xml +```{code-block} xml +:caption: configure.zcml ``` -```python +```{code-block} python +:caption: deserializers.py from plone import api from plone.restapi.deserializer.dxcontent import DeserializeFromJson @@ -150,4 +148,3 @@ class MyDeserializer(DeserializeFromJson): return result ``` -With this, you will be able to manipulate the data that gets on a specific content type. From 479239f629bb16ae37ef17c93e1cde2f31572b57 Mon Sep 17 00:00:00 2001 From: David Glick Date: Thu, 19 Feb 2026 22:12:24 -0800 Subject: [PATCH 4/4] Fix code block captions in customization.md --- docs/source/usage/customization.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/usage/customization.md b/docs/source/usage/customization.md index 30cd855766..8afc159157 100644 --- a/docs/source/usage/customization.md +++ b/docs/source/usage/customization.md @@ -71,7 +71,7 @@ The API automatically provides a default serialization for all Dexterity content To customize the serialization of a given content type, define a custom adapter as shown. ```{code-block} xml -:caption: configure.zcml +:caption: `configure.zcml`