Client libraries

Javascript

The adf-utils client library for JavaScript offers a way to build documents:

To install the library use:

1
2
npm install @atlaskit/adf-utils

Example:

1
2
import { doc, p, emoji } from '@atlaskit/adf-utils/builders';

const adfDoc = doc(
  p('My favourite emoji is ', emoji({ text: '🤦‍♂️', shortName: ':man_facepalming:' }), '. What is yours?'),
);

Produces following output:

1
2
{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "My favourite emoji is "
        },
        {
          "type": "emoji",
          "attrs": {
            "text": "🤦‍♂️",
            "shortName": ":man_facepalming:"
          }
        },
        {
          "type": "text",
          "text": ". What is yours?"
        }
      ]
    }
  ]
}

Java

The adf-builder-java client library provides a fluent document builder. Additional modules, such as adf-builder-java-jackson2 are available to provide JSON support.

See the Quick Start Guide for more information.

Example:

1
2
import com.atlassian.adf.jackson2.AdfJackson2;
import com.atlassian.adf.model.node.Doc;

import static com.atlassian.adf.model.mark.Strong.strong;
import static com.atlassian.adf.model.node.Doc.doc;
import static com.atlassian.adf.model.node.Paragraph.p;
import static com.atlassian.adf.model.node.Rule.hr;
import static com.atlassian.adf.model.node.Text.text;

public class Example {
    public static void main(String[] args) {
        Doc doc = doc(
                p("Hello"),
                hr(),
                p(
                        text("world", strong()),
                        text("!")
                )
        );

        AdfJackson2 parser = new AdfJackson2();
        String json = parser.marshall(doc);
        System.out.println(json);
        Doc reconstructed = parser.unmarshall(json);
        if (!doc.equals(reconstructed)) {
            throw new AssertionError("Hmmmm... they should have matched...");
        }
    }
}

Kotlin

The adf-builder-java Java library was designed to work well in Kotlin directly. In particular:

• Statics and the roots of fluid builders have distinctive names like emoji rather than just builder so that they can all peacefully coexist in the same namespace.
• Nullability handling is strict by default and fully annotated so that the Kotlin compiler knows exactly where null inputs are tolerated.

One small drawback is that the Java library uses Optional wrappers instead of a @Nullable annotation for optional return values. Kotlin code will generally need to unwrap these values with .getOrNull() to reach a more idiomatic data type for that language.

Example:

1
2
    val doc = Doc.doc(
        p("Hello"),
        hr,
        p(
            text("world", strong()),
            text("!")
        )
    )