add more info about RichText field and the usage of transforms and RichTextValue

Author: MrTango

docs/backend/fields.md

@@ -115,6 +115,8 @@ See [`z3c.relationfield`](https://pypi.org/project/z3c.relationfield/) for more
 | `RelationChoice` | `RelationValue` | A `Choice` field intended to store `RelationValue`s | See {ref}`Choice <fields-in-zope-schema-label>` |
 
 
+(backend-fields-richtext-label)=
+
 ### Fields in `plone.app.textfield`
 
 See [`plone.app.textfield`](https://pypi.org/project/plone.app.textfield/) for more details.
@@ -124,6 +126,115 @@ See [`plone.app.textfield`](https://pypi.org/project/plone.app.textfield/) for m
 | `RichText` | `RichTextValue` | Stores a `RichTextValue`, which encapsulates a raw text value, the source MIME type, and a cached copy of the raw text transformed to the default output MIME type. | `IField`, `IRichText` |
 
 
+The RichText field allows for alternative markups and content filtering.
+
+```python
+from plone.app.textfield import RichText
+from plone.supermodel import model
+
+class ITestSchema(model.Schema):
+
+    body = RichText(title="Body text")
+```
+
+The `RichText` field constructor can take the following arguments, in addition to the usual arguments for a `Text` field.
+
+`default_mime_type`
+:   A string representing the default MIME type of the input markup.
+    This defaults to `text/html`.
+
+`output_mime_type`
+:   A string representing the default output MIME type.
+    This defaults to `text/x-html-safe`, which is a Plone-specific MIME type that disallows certain tags.
+    Use the {guilabel}`HTML Filtering` control panel in Plone to control the tags.
+
+`allowed_mime_types`
+:   A tuple of strings giving a vocabulary of allowed input MIME types.
+    If this is `None` (the default), the allowable types will be restricted to those set in Plone's {guilabel}`Markup` control panel.
+
+The *default* field can be set to either a Unicode object (in which case it will be assumed to be a string of the default MIME type) or a {ref}`backend-fields-richtextvalue-label`.
+
+
+#### reStructuredText transformation
+
+Below is an example of a field that allows StructuredText and reStructuredText, transformed to HTML by default.
+
+```python
+from plone.app.textfield import RichText
+from plone.supermodel import model
+
+defaultBody = """\
+Background
+==========
+
+Please fill this in
+
+Details
+-------
+
+And this
+"""
+
+class ITestSchema(model.Schema):
+
+    body = RichText(
+        title="Body text",
+        default_mime_type='text/x-rst',
+        output_mime_type='text/x-html',
+        allowed_mime_types=('text/x-rst', 'text/structured',),
+        default=defaultBody,
+    )
+```
+
+
+(backend-fields-richtextvalue-label)=
+
+#### RichTextValue
+
+The `RichText` field, most of the time does not store a string.
+Instead, it stores a `RichTextValue` object.
+This is an immutable object that has the following properties.
+
+`raw`
+:   A Unicode string with the original input markup.
+
+`mimeType`
+:   The MIME type of the original markup, for example `text/html` or `text/structured`.
+
+`encoding`
+:   The default character encoding used when transforming the input markup.
+    Most likely, this will be UTF-8.
+
+`raw_encoded`
+:   The raw input encoded in the given encoding.
+
+`outputMimeType`
+:   The MIME type of the default output, taken from the field at the time of instantiation.
+
+`output`
+:   A Unicode object representing the transformed output.
+    If possible, this is cached persistently, until the `RichTextValue` is replaced with a new one (as happens when an edit form is saved, for example).
+
+The storage of the `RichTextValue` object is optimized for the case where the transformed output will be read frequently (for example, on the view screen of the content object) and the raw value will be read infrequently (for example, on the edit screen).
+Because the output value is cached indefinitely, you will need to replace the `RichTextValue` object with a new one if any of the transformation parameters change.
+However, as we will see below, it is possible to apply a different transformation on demand, if you need to.
+
+The code snippet below shows how a `RichTextValue` object can be constructed in code.
+In this case, we have a raw input string of type `text/plain` that will be transformed to a default output of `text/html`.
+Note that we would normally look up the default output type from the field instance.
+
+```python
+from plone.app.textfield.value import RichTextValue
+
+context.body = RichTextValue("Some input text", 'text/plain', 'text/html')
+```
+
+The standard widget used for a `RichText` field will correctly store this type of object for you, so it is rarely necessary to create one yourself.
+
+
+
+
+
 ### Fields in `plone.schema`
 
 See {ref}`backend-ploneschema-label` for more details.