Rich Text Fields and Types¶

Storing Text Types¶

Text can be stored along with one of the following text types:

• plain

• markdown

The default text type for a field on a new resource is plain. Text types can be overridden in a PUT or POST request.

When forcing text types, there’s one additional text type that clients may use:

• html

This type cannot be stored, and is only there to provide a rendered version of the text in the resulting payload.

Updating Text Types¶

Text types can be set/updated by setting the appropriate field to either plain or markdown in a POST/PUT request.

Generally, this will be set along with new text matching that text type. However, if the text type is changed in a request without changing the text, the existing stored text will be converted to the new type.

If changing the text type to plain, and the stored text type is markdown, then the existing Markdown text will be unescaped (all '\' characters before Markdown-unsafe characters will be removed).

If changing the text type to markdown, and the stored text type is plain, then the existing plain text will be escaped (all Markdown-unsafe characters will be prefixed by a '\').

Forcing Text Types for Display¶

When retrieving or modifying a resource, the client can force all the text fields to return text using a given text type. By doing this, a client can, for instance, ensure all text will be Markdown-safe, or can be rendered as HTML. This is entirely for the benefit of the client, and does not result in any modifications to the resource itself.

To force the text type, the client must send either a ?force-text-type= query argument (for GET requests) or a force_text_type= form field (for POST/PUT requests) with the given text type.

Text fields can be forced to one of the following text types:

• plain

• markdown

• html

If requesting plain, and the stored text type is markdown, then the Markdown text will be unescaped (all '\' characters before Markdown-unsafe characters will be removed) and returned.

If requesting markdown, and the stored text type is plain, then the text will be escaped (all Markdown-unsafe characters will be prefixed by a '\') and returned.

If requesting html, the text will be rendered for HTML. For plain text, the text will be HTML-escaped, turning special characters into HTML entities. For markdown, the Markdown text will be rendered to HTML in the same way that it’s rendered in the Review Board UI. It’s up to the client to handle any styling.

{
    ...

    "description": "This is a **test**.",
    "description_text_type": "markdown",
    "html_text_fields": {
       "description": "<p>This is a <strong>test</strong>.</p>",
       "description_text_type": "html"
    },
    "raw_text_fields": {
        "description": "This is a **test**.",
        "description_text_type": "markdown"
    },

    ...
}

{
    ...,

    "extra_data": {
        "myextension_text": "This is a **test**.",
        "myextension_text_type": "markdown"
    },
    "html_text_fields": {
        "extra_data": {
            "myextension_text": "<p>This is a <strong>test</strong>.</p>",
            "myextension_text_type": "html"
        }
    },
    "raw_text_fields": {
        "extra_data": {
            "myextension_text": "This is a **test**.",
            "myextension_text_type": "markdown"
        }
    },

    ...
}