Edit ADF in a Forge app

Forge
, ,
1

Dear Community,

Could anyone post a minimal working example of how to create a visual editor for ADF (Atlassian Document Format) in a Forge app? (it doesn’t matter if UI Kit or Custom UI)

I have a use case in which I would need to edit the Description field of an issue in a custom dialog provided by the app, but haven’t yet figured out how this would be possible.

My first try was to import the Atlaskit Editor (Atlaskit by Atlassian ) into a Custom UI module, but no matter how I configured it, it always crashed with rather nondescript exceptions.

Perhaps there is a way to use the ADF schema directly in a ProseMirror instance? Or do you have any other ideas? (Converting ADF to something more standard, like Markdown or HTML and converting it back is risky, I would avoid that if possible).

2

Hello Peter,

Sorry that you’re struggling with an Editor integration. We’re working on a document uplift that should make it easier to work with.
Most commonly people struggle with these two prerequisites of the current Editor version:

  • React 16: at the time of writing, the Atlassian Editor is built on top of React 16 and doesn’t explicitly support any higher versions of React yet, which means both the react and react-dom libraries and their dependencies need to be set to React 16 compatible version.
  • Singleton: the ProseMirror libraries in use and the document format (Atlassian Document Format, ADF) demand that some of the libraries using them are singletons, as multiple versions of the library will cause breaking issues. So, consumers of the Atlassian Editor need to enforce these singletons; this is usually done by deduplicating after installing the dependencies or by setting libraries to specific versions through resolutions to avoid multiple versions. Our recommendation is to use yarn-deduplicate.

If you share the exceptions you’re seeing I’m sure we could help better.

4 Likes
3

Dear Joni,

It seems the deduplication of the dependencies did away with the nondescript exceptions. In a test project, which is a Jira issue activity module, the editor now actually renders, although seemingly without the correct CSS. It is also not possible to edit anything with it (anything entered into the text area is erased immediately). There is no obvious error in the console:

image
image1084×608 3.39 KB

Here is the source code as a Github project: GitHub - petervelosy/atlaskit-editor-test

P.s. could you please give us some pointers for the most basic editor operations (e.g. how to read or write the editor’s content, etc)? Also, a crucial feature for me would be to be able to add non-editable highlights or underline markers (think of a spelling checker) to the text being edited, as I would like to display text analytics in the editor.

4

You’ll need to also set react-dom to version 16. Doing that resulted in a functional editor when I ran the application. atlaskit-editor-test/static/hello-world/package.json at main · petervelosy/atlaskit-editor-test · GitHub
If you can’t get rid of those multiple prosemirror-model versions by deduping you might have to pin them to a fixed version in a resolution.

There is a section in the docs about setting content to the editor: How can I set the content of the editor? in Atlaskit by Atlassian
It also talks about getting the content of the editor through editor actions.

The editor in its current form doesn’t have highlights or underline markers though.

Here’s an example of what an integration could look like:

import React from 'react';

import { EditorContext, WithEditorActions } from '@atlaskit/editor-core';
import { ComposableEditor } from '@atlaskit/editor-core/composable-editor';
import { createDefaultPreset } from '@atlaskit/editor-core/preset-default';

const CommentEditor = () => {
  const presetProps = {
    props: {},
  };
  const defaultPreset = createDefaultPreset(presetProps);
  const initialADFDocument = {
    version: 1,
    type: 'doc',
    content: [
      {
        type: 'paragraph',
        content: [{ type: 'text', text: 'Hello World!' }],
      },
    ],
  };

  return (
    <EditorContext>
      <WithEditorActions
        render={(editorActions) => (
          <ComposableEditor
            preset={defaultPreset}
            defaultValue={initialADFDocument}
            onChange={async () => console.log('The current doc is: ', await editorActions.getValue())}
          />
        )}
      />
    </EditorContext>
  );
};

Hope that helps!

2 Likes
5

Thank you, setting react-dom’s version and adding a resolution to prosemirror-model now results in a working editor.

As for the highlight markers, the two annotation examples here and here would provide an acceptable user experience for me. Could you upload this example somewhere with all of its dependencies? I can unfortunately not run it locally because the published version of @atlaskit/editor-test-helpers does not include /example-inline-comment-component

Alternatively, is there a way to use ProseMirror plugins directly in the editor?