Ace Editor Setup

Setup

Step 1: Add Comment components

Add the Velt Comments component to the root of your app.
This component is required to render comments in your app.
Set the text mode prop to false to hide the default text comment tool.

React / Next.js
Other Frameworks

<VeltProvider apiKey="API_KEY">
  <VeltComments textMode={false} />
</VeltProvider>

<body>
  <velt-comments text-mode="false"></velt-comments>
</body>

Step 2: Install the Velt Ace extension

npm i @veltdev/ace-velt-comments

Step 3: Configure the Ace editor with the Velt Comments extension

React / Next.js
Other Frameworks

import { useEffect, useRef, useCallback } from 'react';
import AceEditor from 'react-ace';
import 'ace-builds/src-noconflict/mode-markdown';
import 'ace-builds/src-noconflict/theme-github';
import { AceVeltComments } from '@veltdev/ace-velt-comments';

function AceEditorComponent() {
  const editorRef = useRef(null);
  const cleanupRef = useRef(null);

  const handleLoad = useCallback((editor) => {
    editorRef.current = editor;
    // Initialize Velt comments - returns a cleanup function
    cleanupRef.current = AceVeltComments(editor);
  }, []);

  useEffect(() => {
    return () => {
      if (cleanupRef.current) {
        cleanupRef.current();
      }
    };
  }, []);

  return (
    <AceEditor
      mode="markdown"
      theme="github"
      name="ace-editor"
      defaultValue="Your initial content here"
      onLoad={handleLoad}
      width="100%"
      height="100%"
    />
  );
}

import * as ace from 'ace-builds';
import 'ace-builds/src-noconflict/mode-markdown';
import 'ace-builds/src-noconflict/theme-github';
import { AceVeltComments } from '@veltdev/ace-velt-comments';

const editor = ace.edit(document.querySelector('#editor'));
editor.setTheme('ace/theme/github');
editor.session.setMode('ace/mode/markdown');
editor.setValue('Your initial content here', -1);

// Initialize Velt comments - returns a cleanup function
const cleanup = AceVeltComments(editor);

// Call cleanup() when done to remove event listeners
// cleanup();

Step 4: Add a comment button to your Ace editor

Add a button that users can click to add comments after selecting text.

React / Next.js
Other Frameworks

import { addComment } from '@veltdev/ace-velt-comments';

// Add this button before <AceEditor> in your JSX
<button
  onMouseDown={(e) => e.preventDefault()}
  onClick={() => {
    if (editorRef.current) {
      addComment({ editor: editorRef.current });
    }
  }}
>
  Add Comment
</button>

<button id="add-comment-btn">Add Comment</button>

import { addComment } from '@veltdev/ace-velt-comments';

const addCommentBtn = document.getElementById('add-comment-btn');
addCommentBtn.addEventListener('mousedown', (e) => e.preventDefault());
addCommentBtn.addEventListener('click', () => {
  addComment({ editor });
});

Step 5: Call `addComment` to add a comment

Call this method to add a comment to selected text in the Ace editor. You can use this when the user clicks on the comment button or presses a keyboard shortcut.
Params: AddCommentRequest. It has the following properties:
- editor: instance of the Ace Editor.
- editorId: Id of the Ace editor. Use this if you have multiple Ace editors on the same page in your app. (optional)
- context: Add any custom metadata to the Comment Annotation. Learn more. (optional)

React / Next.js
Other Frameworks

import { addComment } from '@veltdev/ace-velt-comments';

const addCommentRequest = {
  editor: editorRef.current,
  editorId: 'EDITOR_ID',
  context: {
    storyId: 'story-id',
    storyName: 'story-name',
  },
};

addComment(addCommentRequest);

import { addComment } from '@veltdev/ace-velt-comments';

const addCommentRequest = {
  editor,
  editorId: 'EDITOR_ID',
  context: {
    storyId: 'story-id',
    storyName: 'story-name',
  },
};

addComment(addCommentRequest);

Step 6: Render comments in Ace editor

Get the comment data from Velt SDK and render it in the Ace Editor.
Params: RenderCommentsRequest. It has the following properties:
- editor: Instance of the Ace Editor.
- editorId: Id of the Ace editor. Use this if you have multiple Ace editors on the same page in your app. (optional)
- commentAnnotations: Array of Comment Annotation objects.

React / Next.js
Other Frameworks

import { renderComments } from '@veltdev/ace-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';

const annotations = useCommentAnnotations();

useEffect(() => {
  if (editorRef.current && annotations?.length) {
    const renderCommentsRequest = {
      editor: editorRef.current,
      editorId: 'EDITOR_ID',
      commentAnnotations: annotations,
    };
    renderComments(renderCommentsRequest);
  }
}, [annotations]);

import { renderComments } from '@veltdev/ace-velt-comments';

const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
  if (editor && annotations?.length) {
    const renderCommentsRequest = {
      editor,
      editorId: 'EDITOR_ID',
      commentAnnotations: annotations,
    };
    renderComments(renderCommentsRequest);
  }
});

Step 7: Persist Velt Comment Marks (optional)

By default, Velt comment marks (<velt-comment-text>) are persisted in the Ace editor by Velt SDK. When the editor loads and the Velt SDK initializes, the marks will be automatically added to the editor.
If you plan to store the contents of the Ace editor on your end with the comment marks already included, you can disable this feature.
Default: true

const cleanup = AceVeltComments(editor, {
  persistVeltMarks: false,
});

Step 8: Style the commented text

You can style the commented text by adding CSS for the velt-comment-text element.

velt-comment-text {
  background-color: rgba(255, 255, 0, 0.3);
  border-bottom: 2px solid #ffcc00;
  cursor: pointer;
}

velt-comment-text:hover {
  background-color: rgba(255, 255, 0, 0.5);
}

velt-comment-text.velt-comment-selected {
  background-color: rgba(255, 255, 0, 0.5);
}

APIs

AceVeltComments()

Initializes the Velt Comments extension for an Ace Editor instance.

Params: editor: Ace.Editor, config?: AceVeltCommentsConfig
- editorId?: string - Unique identifier for this editor instance (for multi-editor scenarios)
- persistVeltMarks?: boolean - Whether to persist Velt marks. Default: true
Returns: () => void - Cleanup function to remove event listeners

React / Next.js
Other Frameworks

import { useRef, useCallback } from 'react';
import AceEditor from 'react-ace';
import { AceVeltComments } from '@veltdev/ace-velt-comments';

function AceEditorComponent() {
  const editorRef = useRef(null);
  const cleanupRef = useRef(null);

  const handleLoad = useCallback((editor) => {
    editorRef.current = editor;
    cleanupRef.current = AceVeltComments(editor, {
      editorId: 'my-editor',
      persistVeltMarks: true,
    });
  }, []);

  return (
    <AceEditor
      onLoad={handleLoad}
      mode="markdown"
      theme="github"
      name="ace-editor"
    />
  );
}

import * as ace from 'ace-builds';
import { AceVeltComments } from '@veltdev/ace-velt-comments';

const editor = ace.edit(document.querySelector('#editor'));

const cleanup = AceVeltComments(editor, {
  editorId: 'my-editor',
  persistVeltMarks: true,
});

// Later, when done:
cleanup();

addComment()

Creates a comment annotation for the currently selected text in the editor.

Params:
- request: AddCommentRequest
  - editor: Ace.Editor
  - editorId?: string
  - context?: object
Returns: Promise<void>

React / Next.js
Other Frameworks

import { addComment } from '@veltdev/ace-velt-comments';

<button
  onMouseDown={(e) => {
    e.preventDefault();
    addComment({
      editor: editorRef.current,
      editorId: 'my-editor',
      context: { customData: 'value' }
    });
  }}
>
  Comment
</button>

import { addComment } from '@veltdev/ace-velt-comments';

addComment({
  editor,
  editorId: 'my-editor',
  context: { customData: 'value' },
});

renderComments()

Renders and highlights comment annotations in the editor.

Params:
- request: RenderCommentsRequest
  - editor: Ace.Editor
  - editorId?: string
  - commentAnnotations?: CommentAnnotation[]
Returns: void

React / Next.js
Other Frameworks

import { useEffect } from 'react';
import { renderComments } from '@veltdev/ace-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';

const annotations = useCommentAnnotations();

useEffect(() => {
  if (editorRef.current && annotations) {
    renderComments({
      editor: editorRef.current,
      editorId: 'my-editor',
      commentAnnotations: annotations,
    });
  }
}, [annotations]);

import { renderComments } from '@veltdev/ace-velt-comments';

const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
  if (editor && annotations) {
    renderComments({
      editor,
      editorId: 'my-editor',
      commentAnnotations: annotations,
    });
  }
});

​Setup

​Step 1: Add Comment components

​Step 2: Install the Velt Ace extension

​Step 3: Configure the Ace editor with the Velt Comments extension

​Step 4: Add a comment button to your Ace editor

​Step 5: Call addComment to add a comment

​Step 6: Render comments in Ace editor

​Step 7: Persist Velt Comment Marks (optional)

​Step 8: Style the commented text

​APIs

​AceVeltComments()

​addComment()

​renderComments()

Setup

Step 1: Add Comment components

Step 2: Install the Velt Ace extension

Step 3: Configure the Ace editor with the Velt Comments extension

Step 4: Add a comment button to your Ace editor

Step 5: Call `addComment` to add a comment

Step 6: Render comments in Ace editor

Step 7: Persist Velt Comment Marks (optional)

Step 8: Style the commented text

APIs

AceVeltComments()

addComment()

renderComments()