Rich Text Field

The Rich Text field allows single- or multi-line text input with special formatting such as bold, italic and strikethrough text, as well as block formats such as lists, quotes and more.

Editing UI Widget

This field is displayed as a text editor labelled with the field’s label in the Content Editor. It features a dynamic toolbar that gives easy access to undo and redo actions, as well as the activated formatting options for that specific field.

Output Format

The Rich Text field outputs the text as a string. Depending on the outputFormat option, the string may be in HTML or Markdown.

Options

The following options are available for this field (default values shown):

{
  "outputFormat": "html",
  "blockFormats": [
    "blockquote",
    "heading",
    "hr",
    "orderedList",
    "unorderedList",
    "image"
  ],
  "inlineFormats": [
    "em",
    "strong",
    "link"
  ],
  "formatOptions": [
    "allowQuoteFooters",
    "allowNestedLists",
    "allowImageCaptions"
  ],
  "inputRuleOptions": [
    "autoquotes",
    "dashes",
    "ellipsis",
    "noDoubleCaps",
    "noDoubleSpace"
  ],
  "minHeading": 2,
  "maxHeading": 4,
  "codeLangs": [
    "html",
    "css",
    "javascript",
    "markdown"
  ],
  "allowRaw": false,
  "urlTemplate": "",
  "urlSuffix": "",
  "linkOptions": [
    "forceBlankTarget",
    "allowExternal",
    "allowInternal"
  ]
}

• outputFormat: determines the format the text is saved in. May be either ‘html’ or ‘markdown’

• blockFormats: a list of block formats that are allowed in this field. If none are allowed, the editor will be inline-only and not allow any line-breaks. Possible formats are:

  • blockquote for quotes

  • codeBlock for code blocks

  • heading for headings

  • hr for horizontal rules

  • orderedList for numbered lists

  • unorderedList for bullet lists

  • images for images (currently not implemented)

• inlineFormats: a list of inline formats that are allowed in this field. Possible formats are:

  • br for hard line breaks (entered with Ctrl or Shift+Return)

  • code for inline code

  • em for italics

  • link for links

  • strike for strikethrough

  • strong for bold

• formatOptions: these are additional options for block formats

  • allowQuoteFooters: allow a special “Quote Footer” format at the end of blockquotes that renders a footer (displayed as a lighter text with a leading em-dash in the editor) in HTML mode

  • allowNestedLists: allow lists to be nested within each other

  • allowImageCaptions: allows captions below images in HTML mode

• inputRuleOptions: these features automatically substitute entered text with typographically correct symbols and prevent common mistakes when active

  • autoquotes: use smart quotes, i.e. replace second and minute marks (' and ") with their typographically correct symbols. These symbols can be set up per-language in the project configuration

  • dashes: automatically replace consecutive dashes with en- and em-dashes

  • ellipsis: automatically replace three consecutive periods with a single ellipsis character

  • noDoubleCaps: automatically lower-case the second letter in a word if both first letters but no others in the word are capitalised

  • noDoubleSpace prevent consecutive spaces

• minHeading: the minimum heading level from 1 to 6, referring to HTML headings, i.e. 1 is the primary heading, 2 is the first subheading, etc.

• maxHeading: the maximum heading level from 1 to 6

• codeLangs: the code languages available to format code blocks with, will be set as the data-lang attribute for the pre-element and added as a class in the form of language-xyz

• allowRaw: when enabled allows the editor to be switched to a raw text editor with access to the underlying source code of the added rich text for low-level modification

• urlTemplate: a custom URL template to use for internal links to override the template set for the Collection

• urlSuffix: a suffix to append to the file path for internal links if no URL-template is set for the Collection and none is provided in the “urlTemplate” field or the “useFilePath” link option is active

• linkOptions: determines what attributes are set on links inserted through the editor UI

  • forceBlankTarget forces target="_blank" to be added to links

  • forceNofollow forces rel="nofollow" on links

  • useFilePath uses the path of the file instead of the URL template for internal links

  • allowExternal allows the addition of external links

  • allowInternal allows the addition of internal links

Validation

The following validation options are available for this field (default values shown):

{
  "enforceMinMax": true,
  "max": null,
  "min": null,
  "regex": null,
  "regexError": null,
  "required": false,
  "unit": "length"
}

Notes

Despite having an option to allow images as block formats, it is currently not possible to add images in the field without using the raw editor. This feature is currently under development.

If allowRaw is set to true and the raw content of a Rich Text field is edited, be aware that any custom additions (such as using formatting that is not allowed by the field’s options) will be stripped out if you switch back to the rendered mode of the field and change something.

Rich Text fields can be highly customised to lock down what formatting is allowed in a particular field and what isn’t. To allow only inline formats and no line-breaks, simply disable all block formats, i.e. set blockFormats to an empty array.

Since there should only be one H1 per page, it’s often advisable to limit the maximum heading to 2 for rich text editors with headings enabled.

If outputFormat is set to markdown not all formatting options may be available and activated, as Markdown only supports certain types of text formatting.

Embedded Images

When images are allowed in a Rich Text field with outputFormat === html, they are inserted as <figure> elements containing an <img> tag and an optional <figcaption> tag, if captions are allowed. For Rich Text fields outputting Markdown, the image is added as a standard ![Alt text](/path/to/image.jpg) Markdown image.

If the Advanced Media Library is activated, fields keyed alt and title will be set directly on the <img> tag (HTML), or the Markdown image. All other fields will be serialised to data-* properties on the <img> tag (HTML) and discarded in Markdown, since Markdown doesn’t support metadata beyond alt and title on images.

If the Advanced Media Library is not activated, alt and title information can still be set on the images, it just won’t be pre-populated based on a central metadata file.

Version History

• In version 0.3.0 of Mattrbld the allowImageCaptions option was added, which is enabled for new rich text fields, but disabled for rich text fields in existing Schemas

• Version at launch: 1