ADF node: mediaSingle

Description

The mediaSingle node is a container for one media item. This node enables the display of the content in full, in contrast to a mediaGroup that is intended for a list of attachments. A common use case is to display an image, but it can also be used for videos, or other types of content usually renderable by an @atlaskit/media card component.

For Confluence, the media node may optionally be followed by a caption¹ containing a brief description or other commentary concerning the image.

Implementation Note: Although mediaSingle uses the content section to wrap other nodes, its behaviour is very different from most other content nodes in that it can only contain exactly one or two nodes, and those two nodes differ in type. This does not work well with the ContentNode interface in the Java code, so the MediaSingle class does not implement that interface at all.

Example

Java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
doc(
        p("Hello"),
        mediaSingle()
                .alignStart()
                .media(
                        Media.fileMedia()
                                .id("ABC-123")
                                .collection("some-collection-id")
                                .occurrenceKey("some-occurrence-key")
                                .size(640, 480)
                ),
        p("World"))
);

ADF

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "Hello"
        }
      ]
    },
    {
      "type": "mediaSingle",
      "content": [
        {
          "type": "media",
          "attrs": {
            "width": 640,
            "height": 480,
            "id": "ABC-123",
            "type": "file",
            "collection": "some-collection-id",
            "occurrenceKey": "some-occurrence-key"
          }
        }
      ],
      "attrs": {
        "layout": "align-start"
      }
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "World"
        }
      ]
    }
  ]
}

Result

Hello

World

Compatibility

Products

Usage

• BlockquoteContent
• BodiedSyncBlockContent
• DocContent
• ExtensionFrameContent
• LayoutColumnContent
• ListItemContent
• NestedExpandContent
• NonNestableBlockContent
• PanelContent
• TableCellContent

Marks

❌ N/A²

Structure

• type - mediaSingle
• content - array(media, caption?)
• attrs?
  • width? - number - valid range depends on widthType:
    • percentage (default) – [0.0, 100.0]
    • pixel – non-negative integer; an upper limit of 1800 is recommended, but it is not enforced
  • widthType?³ - percentage | pixel
  • layout⁴ - wide | full-width | center | wrap-right | wrap-left | align-end | align-start
  • localId? – string⁵
• marks? - array(link) – DEPRECATED²

---

Footnotes

1. There is very little documentation available for caption, even internally at Atlassian. This documentation will be improved once that information is available. ↩

2. The mediaSingle node will tolerate the presence of a link mark, but this is deprecated. The link should be placed directly on the media node, instead. ↩ ↩²

3. The widthType defines the unit of measurement for width, with percentage assumed by default ↩

4. The layout controls the placement of this image relative to other content in the document. The wrap-left and wrap-right options “float” this image to the left or right respectively with other content “flowing” beside it. The center option treats this content as its own block, and wide does the same, but bleeds into the margins. The full-width option stretches the image across the entire page. ↩

5. The localId, when present, will typically be a random UUID. This is not enforced by the schema. ↩