Rich content often has to go somewhere that cannot display it, such as an email subject line, a notification, a log message, or a full-text search index. For these, ADF can be rendered as plain text, which here means text with no styling. Bold, italics, colors, and the other marks are dropped, and by default so are link targets and mention IDs.
Some of the document's structure still survives as simple textual markers. List items start with * or 1. , quotes start with > , table rows are written as |cell|cell|, and media, extensions, and other nodes with no textual form are replaced by short placeholders such as [media]. These markers come from the Atlaskit editor's text renderer and are meant for a human reader. Nothing is escaped, so text that happens to start with * or contain | looks just like a list or a table, and the output cannot be parsed back into ADF. Callers who need structure that can be read back should use Markdown instead.
Converting ADF to plain text is therefore lossy, and what is worth keeping depends on what the text is for. A search index benefits from link targets and mention IDs, while a notification preview usually does not. The configuration controls these choices.
Historically, this library provided plain text through Node.toPlainText(), which each node implements for itself. Its behavior could only be adjusted through the Feature Context, which made it awkward to offer more than a couple of options. PlainTextTransformer replaces it with a single transformer whose output is controlled by an ordinary configuration object. Node.toPlainText() is now deprecated and will be removed in a future major release.
PlainTextTransformer is part of the core adf-builder-java module, in the com.atlassian.adf.plaintext package, so no additional dependency is required. Along with PlainTextConfig and PlainText, it should be considered EXPERIMENTAL. Its default output is verified against Node.toPlainText(), but its API is subject to change.
1 2 3 4 5 6 7 8 9 10doc( p(text("See "), text("the docs").link("https://example.com/docs"), text(" and ask "), mention("abc123")), blockCard("https://example.atlassian.net/browse/ABC-123"), ul( li(p("First")), li(p("Second")) ), mediaSingle(fileMedia("file-id", "coll").alt("diagram.png")) )
1 2 3 4PlainTextTransformer transformer = new PlainTextTransformer(); String text = transformer.toPlainText(doc); // text == "See the docs and ask @unknown\n* First\n* Second\n[media]"
With no configuration, the output is identical to that of Node.toPlainText() with no features enabled.
With the default configuration, the nodes that this library supports are rendered as shown in this table.
| ADF node | Plain-text output |
|---|---|
paragraph, heading, caption, codeBlock | inline content run together and trimmed, with a space added after a mention that is followed directly by text |
doc, expand, nestedExpand, layoutSection, layoutColumn, bodiedRule, bodiedSyncBlock, taskList, decisionList | one block per line, with blank lines collapsed and any expand title dropped |
panel | one block per line, with blank lines kept, though a doc or other container in the row above that holds the panel collapses them along with the rest of its content |
blockquote | > followed by its blocks run together |
bulletList, orderedList | * item or 1. item, numbered from the list's order, with nested lists not indented |
taskItem, blockTaskItem, decisionItem | [] item or [x] item for a task, and <> item for a decision |
table | one row per line, as |cell|cell| |
hardBreak | a line break |
rule | nothing |
text | the text alone, with all marks including links dropped |
mention | its text, or @unknown when it has none, with @all and @here kept as they are |
emoji | the emoji character, or its short name (e.g. :grin:) |
date | YYYY-MM-DD |
status | [ TEXT ] in capitals |
placeholder | its text |
inlineCard | its URL |
blockCard, embedCard | nothing |
mediaSingle | [media], followed by the caption |
mediaGroup | a count of its files (e.g. ๐ 2 Files) |
mediaInline | [mediaInline] |
extension, inlineExtension, bodiedExtension, multiBodiedExtension | its text attribute, otherwise its node type in brackets (e.g. [extension]) |
syncBlock | [syncBlock] |
Nodes that this library does not recognize render their text or attrs.text property if they have one, and otherwise their node type in brackets.
A PlainTextConfig controls how the nodes whose plain-text form is lossy are rendered. It is immutable, so it can be defined once and shared between transformers, and its builder starts from the defaults, so only the settings that should differ need to be given.
1 2 3 4 5 6 7 8 9 10 11PlainTextConfig config = PlainTextConfig.builder() .mentions(MentionStyle.NAME_AND_ID) .links(LinkStyle.TEXT_AND_URL) .media(MediaStyle.ALT_TEXT_AND_ID) .cards(CardStyle.URL) .build(); PlainTextTransformer transformer = new PlainTextTransformer(config); String text = transformer.toPlainText(doc); // text == "See the docs (https://example.com/docs) and ask @[abc123]\n" // + "https://example.atlassian.net/browse/ABC-123\n* First\n* Second\n[diagram.png (file-id)]"
Each setting has the styles shown in this table. The last column shows which styles the defaults() and detailedText() settings use.
| Setting | Style | Renders | Used by |
|---|---|---|---|
mentions (mention) | UNKNOWN_WHEN_NAMELESS | @Fred, or @unknown when it has no name | defaults(), detailedText() |
ID_WHEN_NAMELESS | @Fred, or @[abc123] when it has no name | ||
NAME_AND_ID | @Fred (abc123), or @[abc123] when it has no name | ||
ID_ONLY | @[abc123] | ||
links (link marks) | TEXT_ONLY | docs | defaults(), detailedText() |
TEXT_AND_URL | docs (url), and [media] (url) for linked media | ||
media (media, mediaSingle, mediaInline, and the items of a mediaGroup) | PLACEHOLDER | [media] or [mediaInline] | defaults() |
ALT_TEXT_AND_ID | [alt (id)], or [id] when it has no alt text | detailedText() | |
ALT_TEXT | [alt], or [media] when it has no alt text | ||
mediaGroups (mediaGroup) | FOLLOW_MEDIA | COUNT under PLACEHOLDER media, and ITEMS under the other media styles | defaults() |
COUNT | ๐ 2 Files | ||
ITEMS | [media], [media] | ||
COUNT_AND_ITEMS | ๐ 2 Files: [media], [media] | detailedText() | |
extensions (extension, inlineExtension, bodiedExtension, multiBodiedExtension) | NODE_TYPE | its text, or [inlineExtension] | defaults() |
KEY_AND_CONTENT | its text, or [inlineExtension:jira], then its body on a new line | detailedText() | |
TEXT_ONLY | its text, then its body on a new line | ||
PLACEHOLDER_ONLY | [inlineExtension:jira] | ||
OMIT | nothing | ||
cards (blockCard, embedCard) | OMIT | nothing | defaults() |
URL | its URL, or nothing for a blockCard with none | ||
URL_OR_PLACEHOLDER | its URL, or [blockCard] for a blockCard with none | detailedText() | |
PLACEHOLDER | [blockCard] or [embedCard] | ||
inlineCards (inlineCard) | URL | its URL | defaults() |
TYPED_ISSUE_KEY_OR_URL | ABC-123 for a card made from an issue key typed as text, otherwise its URL | detailedText() | |
blockquotes (blockquote) | CONCATENATED | > followed by its blocks run together | defaults() |
SEPARATED | each block on its own line, with > at the start of every line | detailedText() | |
blankLines (the whole document) | COLLAPSED | no blank lines | defaults() |
CONTENT_ONLY | only the blank lines in the content | detailedText() | |
AS_RENDERED | every blank line, including empty paragraphs | ||
expands (expand, nestedExpand) | CONTENT_ONLY | its content | defaults() |
TITLE_AND_CONTENT | its title, then its content on a new line | detailedText() | |
lists (bulletList, orderedList) | FLAT | nested lists not indented | defaults() |
INDENTED | nested lists indented under their item, as in * a\n * b | detailedText() | |
unsupported (nodes the library could not parse) | NODE_TYPE | its text, or its node type in brackets | defaults(), detailedText() |
TEXT_ONLY | its text, or nothing | ||
syncBlocks (syncBlock) | PLACEHOLDER | [syncBlock] | defaults(), detailedText() |
RESOURCE_ID | [some-resource-id] | ||
rules (rule) | OMIT | nothing | defaults() |
DASHES | ---- | detailedText() | |
emptyBlocks (codeBlock, panel, expand, nestedExpand) | OMIT_IF_BLANK | nothing when the block has no text | defaults() |
PLACEHOLDER_IF_BLANK | [codeBlock], [panel], [expand] or [nestedExpand] when the block has no text | detailedText() |
A few more points about these settings.
TEXT_AND_URL shows a link's URL once, after the whole link, and not at all when the text already is the URL.mediaGroup count stands for the whole group, so it shows none of its files' URLs. Listed items show their own.inlineCard follows the inlineCards setting, whatever the cards setting.inlineCard from an issue key typed as text, such as See ABC-123 in wiki markup, it marks the card's URL with #icft=KEY, as in https://example.atlassian.net/browse/ABC-123#icft=ABC-123. TYPED_ISSUE_KEY_OR_URL renders such a card as its key, ABC-123, as it was typed. A pasted link to an issue has no marker, so it still renders as its URL.PlainTextConfig.detailedText() gives settings for the document's text with its details, the things that say what each part of the document is or holds. The document's own text is written in reading order, including the body of an extension and the title of an expand, and an issue key typed as text that became an inline card is written as the key that was typed. Content that the document only refers to is identified rather than shown. Media renders as its alt text and ID, since ADF holds no file names, a media group as a count of its files followed by each of them, an inline card that was not typed as an issue key as its URL, a block or embed card as its URL, or [blockCard] when it has none, and a sync block as [syncBlock]. An extension with no text renders as its node type and key, such as [inlineExtension:jira], and a bodied extension follows this with its body on a new line, since an app can show, hide, or transform the body. A node the library cannot render shows its text, or otherwise its node type, such as [someNewNode].
The structure a reader sees is kept. Nested lists are indented, each line of a blockquote starts with > , and list markers, check boxes, table cell separators, and status brackets remain. A rule renders as ----, and a code block, panel or expand with no text as its node type, such as [codeBlock], since a reader still sees it. Only the blank lines in the content are kept.
1 2 3PlainTextTransformer transformer = new PlainTextTransformer(PlainTextConfig.detailedText()); String text = transformer.toPlainText(doc);
The text is close to what a reader sees, but not the same, as it holds the details that identify what the page shows. Where the page shows an image, a preview, or a macro's output, the text has the alt text and ID, the URL, or a placeholder that stands for it. Start from it with PlainTextConfig.detailedText().copy() to change any of its settings.
Unlike Node.toPlainText(), the transformer ignores the Feature Context, so its output depends on its configuration alone.
Many uses of plain text only need part of it: whether a description is blank, whether it mentions something, or perhaps the first couple of hundred characters for a preview. plainText(node) returns a PlainText that answers these without rendering the whole document.
1 2 3 4 5 6 7PlainText text = new PlainTextTransformer().plainText(issue.getDescription()); if (text.isBlank()) { return Optional.empty(); } boolean mentionsOutage = text.contains("outage"); String preview = text.truncate(200);
With the document from the example above, whose full text is "See the docs and ask @unknown\n* First\n* Second\n[media]":
1 2 3 4 5 6PlainText text = new PlainTextTransformer().plainText(doc); text.isBlank(); // false, after rendering only the first paragraph text.contains("First"); // true, after rendering the list as well text.contains("Third"); // false, after rendering the rest text.truncate(12); // "See the docs", from the text already rendered
A document whose blocks render only whitespace, or nothing at all, is blank, and truncate never cuts an emoji in half:
1 2 3 4PlainTextTransformer transformer = new PlainTextTransformer(); transformer.plainText(doc(p(" "), rule(), p())).isBlank(); // true transformer.plainText(doc(p("Ship it ๐"))).truncate(9); // "Ship it ", since ๐ takes two characters
isBlank(), isEmpty(), and contains(value) give the same answers as the String methods of the same names would on the full text.
truncate(maxLength) gives the start of the text, at most maxLength chars long. It never cuts a character in the middle. Emoji, flags, and letters with accents or other marks can take up more than one char and are kept whole, so the result can be a little shorter than maxLength, or empty if the first character is longer. A result shorter than maxLength is therefore not a sign that it is the whole text. Keeping characters whole is a best effort: some joined letters, such as เคเฅเคท, can still be cut between their parts, and so can a character longer than any people write, such as a letter carrying dozens of accents, which only text made to be awkward has.
maxLength counts chars, not the characters a reader sees. Some chars take up no space on screen but still count:
char when stored as a single character and two when stored as e followed by the combining acute accent U+0301, though both look the sametoString() gives the entire transformed text.
Because a PlainText keeps what it has rendered, the node must not be changed while the PlainText is in use. Instances are not safe for use by more than one thread at a time.
Replacing node.toPlainText() with new PlainTextTransformer().toPlainText(node) gives the same output, as long as no features are enabled. Callers that do enable the plain-text features, including through Context.GlobalDefaultFeatureProvider, should set the matching configuration instead, since the transformer ignores them.
1 2 3 4 5 6PlainTextConfig config = PlainTextConfig.builder() .mentions(MentionStyle.ID_WHEN_NAMELESS) // was Feature.PLAINTEXT_MENTION_USE_ID .cards(CardStyle.URL) // was Feature.ENABLE_BLOCK_EMBED_CARD_URLS_PLAINTEXT .build(); String text = new PlainTextTransformer(config).toPlainText(doc);
The Feature.PLAINTEXT_MENTION_USE_ID and Feature.ENABLE_BLOCK_EMBED_CARD_URLS_PLAINTEXT enum constants are deprecated and will be removed along with Node.toPlainText() in a future major release.
Rate this page: