​
Custom filtering, sorting and grouping

  • Here is the overview on how it works:
    • Enable custom actions in the comments sidebar.
    • Add Velt Button Wireframe to the sidebar wireframe.
    • Handle click events and lifecycle events to apply custom filtering, sorting, and grouping logic.
    • Update sidebar data.
  • Here are the steps to implement it:
1

Enable Custom Actions

Using Props:
<VeltCommentsSidebar customActions={true} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableSidebarCustomActions();
commentElement.disableSidebarCustomActions();
2

Add Velt Buttons and handle click events

  • Learn more about how to setup Velt Button Wireframe.
  • Set default state using the active prop.
  • Handle veltButtonClick event to implement custom filtering, sorting, and grouping logic. It returns VeltButtonClickEvent.
<VeltWireframe>
  <VeltCommentsSidebarWireframe.Panel>
      <VeltCommentsSidebarWireframe.Header />
      <div className="custom-filter-chip-container">

          <VeltButtonWireframe id="unread" type="multi-select" group="custom-filter" active={true}>
              <div className="custom-filter-chip-button">Unread</div>
          </VeltButtonWireframe>

          <VeltButtonWireframe id="mentions" type="multi-select" group="custom-filter">
              <div className="custom-filter-chip-button">Mentions</div>
          </VeltButtonWireframe>

      </div>
  </VeltCommentsSidebarWireframe.Panel>
</VeltWireframe>
Handle the button click event:
const veltButtonClickEventData = useVeltEventCallback('veltButtonClick');
useEffect(() => {
  if (veltButtonClickEventData) {
    if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
      const selections = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
      if (selections?.unread) {
        // show unread comments
      }
      if (selections?.mentions) {
        // show comments with mentions
      }
    }
  }
}, [veltButtonClickEventData]);
3

Handle Sidebar data lifecycle events

  • There are two lifecycle events you need to handle to implement custom filtering, sorting, and grouping logic:
    • commentSidebarDataInit: Triggered when comment sidebar data is first loaded. It returns CommentSidebarDataInitEvent
    • commentSidebarDataUpdate: Triggered when comment sidebar data is updated. It returns CommentSidebarDataUpdateEvent
      • This event can trigger multiple times when either the comment data or unread comment count changes.
    const commentSidebarDataInitEvent: CommentSidebarDataInitEvent = useCommentEventCallback('commentSidebarDataInit');
const commentSidebarDataUpdateEvent: CommentSidebarDataUpdateEvent = useCommentEventCallback('commentSidebarDataUpdate');

useEffect(() => {
  if (commentSidebarDataInitEvent) {
    // Custom Filtering | Sorting | Grouping Logic
  }
}, [commentSidebarDataInitEvent]);

useEffect(() => {
  if (commentSidebarDataUpdateEvent) {
    // Custom Filtering | Sorting | Grouping Logic
  }
}, [commentSidebarDataUpdateEvent]);
4

Update sidebar data based on custom logic

  • Once you have applied your custom filtering, sorting, and grouping logic, create the data an array of CommentSidebarData objects and set it in the comments sidebar.
  • Use the options parameter to control if you want to group the comments or not. 
    const options = {
  grouping: false
};

const customFilterData = [
  {
    "groupId": "group1",
    "groupName": "Group 1",
    "isExpanded": true,
    "annotations": [
      {
          ...annotation1
      },
      {
          ...annotation2
      },
    ]
  }
];

const commentElement = client.getCommentElement();
commentElement.setCommentSidebarData(customFilterData, options);

​
Navigation

​
onCommentClick

  • Listen for click events on comments in the sidebar to trigger actions like navigation.
  • The event callback provides access to the clicked comment’s annotation object, which includes location and context data.
  • Use this data to update your app’s state and navigate to the comment’s location.
The event handler receives an object with the following properties:
PropertyTypeDescription
documentIdstringID of the document containing the comment
locationObjectLocation details of the comment
targetElementIdstringDOM ID of the element the comment is attached to
contextObjectCustom context data associated with the comment
annotationCommentAnnotationThe full comment annotation object
 <VeltCommentsSidebar onCommentClick={onCommentClick} /> 

// event handler for when a comment is clicked on 
const onCommentClick = (event) => {
  //handle custom navigation by getting location if you have set custom locations
  const { pageId } = event.location;
  //handle custom navigation by getting context if you have added metadata using addContext()
  const { pageId } = event.context;
  yourNavigateToPageMethod(pageId);
};

​
onCommentNavigationButtonClick

  • This event is triggered when the navigation button in the comment dialog in the Sidebar is clicked.
  • Use this event to implement custom navigation logic.
<VeltCommentsSidebar onCommentNavigationButtonClick={onCommentNavigationButtonClick} />

  // event handler for when a comment is clicked on 
  const onCommentNavigationButtonClick = (event) => {
    console.log('onCommentNavigationButtonClick', event);
    //handle custom navigation by getting location if you have used Locations
    const { pageId } = event.location;
    //handle custom navigation by getting context if you have used addContext()
    const { pageId } = event.context;
    yourNavigateToPageMethod(pageId);
  };

​
enableSidebarUrlNavigation

  • By default, clicking a comment in the sidebar doesn’t automatically update the page URL where the comment was added.
  • Use this to enable automatic URL navigation when clicking comments in the sidebar.
  • If your app’s state is more complex, you might need to listen for onCommentClick events and implement custom navigation logic.
Default: false
Using Props:
<VeltCommentsSidebar urlNavigation={true} />
Using API method:
const commentElement = client.getCommentElement();
// to enable sidebar url navigation
commentElement.enableSidebarUrlNavigation();
// to disable sidebar url navigation
commentElement.disableSidebarUrlNavigation();

​
UI

​
currentLocationSuffix

  • Adds “(this page)” suffix to the group name when the current location matches the group’s location.
Default: false 
<VeltCommentsSidebar currentLocationSuffix={true}/>

​
embedMode

  • By default, the sidebar will open up from the right corner of the page.
  • With embed mode, you can add the sidebar in your component and it will take up the full width and height of its container.
  • When in embed mode, the sidebar will not have the close button. You need to implement your own open and close functionality on the host component.
<div className="sidebar-container">
  <VeltCommentsSidebar embedMode={true} />
</div>

​
excludeLocationIdsFromSidebar

  • Use this to filter out comments from certain locations. These comments will not be displayed in the sidebar.
Using Props:
<VeltCommentsSidebar excludeLocationIds={['location1', 'location2']} />
Using API:
const commentElement = client.getCommentElement();
commentElement.excludeLocationIdsFromSidebar(['location1', 'location2']);

​
filterPanelLayout

  • Change the layout of the filter panel in the sidebar.
  • Options: menu or bottomSheet Default: bottomSheet
<VeltCommentsSidebar filterPanelLayout="menu"/>

​
filterOptionLayout

  • Change the layout of the filter options in the sidebar filter panel.
  • Options:
    • checkbox: (default) to show the filter options in a checkbox list
    • dropdown: to show the filter options in a searchable dropdown with checklist
<VeltCommentsSidebar filterOptionLayout="dropdown"/>

​
filterCount

  • Disable comment count on filter options. This leads to better performance.
<VeltCommentsSidebar filterCount={false}/>

​
floatingMode

  • This makes the sidebar open in an overlay panel over the sidebar button float over the page content.
<VeltSidebarButton floatingMode={true} />

​
focusedThreadMode

  • In this mode, when you click on a comment in the sidebar, it opens the thread in an expanded view within the sidebar itself.
  • Other threads and actions like filters, search etc. are hidden behind a back button.
  • Enabling this mode also adds a navigation button in the comment dialog. Clicking it will navigate to the comment and trigger a callback. Learn more about it here.
If you had previously used a wireframe for the comment dialog, you will need to add the navigation button wireframe and the focused thread wireframe.
<VeltCommentsSidebar focusedThreadMode={true} />

​
pageMode

  • This adds a composer in the sidebar where users can add comments without attaching them to any specific element.
Default: false 
<VeltCommentsSidebar pageMode={true} />

​
position

  • Change the default direction where the sidebar opens from.
  • Options: left or right
  • Default: right
<VeltCommentsSidebar position="left"/>

​
openCommentSidebar

const commentElement = client.getCommentElement();
commentElement.openCommentSidebar(); // opens the comments side bar
commentElement.closeCommentSidebar(); // closes the comments side bar
commentElement.toggleCommentSidebar(); // toggles the comments side bar

​
searchPlaceholder

  • Customize the placeholder text shown in the search input of the comments sidebar.
  <VeltCommentsSidebar searchPlaceholder="New placeholder" />

​
sidebarButtonCountType

  • Change the count shown on the sidebar button.
    • default: Shows the total count of comments in open and in progress states. (default)
    • filter: Shows the count of filtered comments.
Using Props:
  <VeltCommentsSidebar sidebarButtonCountType="filter" />
  <VeltSidebarButton sidebarButtonCountType="filter" />
Using APIs:
const commentElement = useCommentUtils();
commentElement.setSidebarButtonCountType('filter');

​
System Filters, Sorting and Grouping

​
filterConfig

  • Customize the available system filters:
  • location: Filter comments by location.
  • document: Filter comments by document.
  • people: Filter comments by author of comment annotation.
  • involved: Filter comments by users who are involved in the comment annotation (author, mentioned, assigned).
  • tagged: Filter comments by users who were tagged/mentioned in the comment. Only available in the latest SDK version.
  • assigned: Filter comments by users who were assigned to the comment. Only available in the latest SDK version.
  • priority: Filter comments by priority.
  • category: Filter comments by category.
  • status: Filter comments by status.
  • You can rename, disable, configure grouping, and multi-select behavior of the filters as needed. 
const filterConfig = {
  location: {
    enable: true,
    name: "Pages",
    enableGrouping: true,
    multiSelection: true,
    placeholder: "Filter by location",
    order: ['locationId1', 'locationId2', 'locationId3']
  },
  document: {
    enable: true,
    name: "Documents",
    enableGrouping: true,
    placeholder: "Filter by document",
    multiSelection: true,
  },
  people: {
    enable: true,
    name: "Author",
    enableGrouping: true,
    placeholder: "Filter by author",
    multiSelection: true,
  },
  involved: {
    enable: true,
    name: "Involved",
    enableGrouping: false,
    placeholder: "Filter by involved",
    multiSelection: true,
  },
  tagged: {
    enable: true,
    name: "Tagged",
    enableGrouping: false,
    placeholder: "Filter by tagged",
    multiSelection: true,
  },
  assigned: {
    enable: true,
    name: "Assigned",
    enableGrouping: false,
    placeholder: "Filter by assigned",
    multiSelection: true,
  },
  priority: {
    enable: true,
    name: "Priority",
    enableGrouping: false,
    placeholder: "Filter by priority",
    multiSelection: true,
  },
  category: {
    enable: true,
    name: "Category",
    enableGrouping: true,
    placeholder: "Filter by category",
    multiSelection: true,
  },
  status: {
    enable: true,
    name: "Status",
    placeholder: "Filter by status",
    multiSelection: true,
  }
};
<VeltCommentsSidebar filterConfig={filterConfig} />

​
groupConfig

  • Enable/disable the option to group comments in the sidebar with the group config attribute:
const groupConfig = {
  enable: true,
  name: "Custom Group By",
};

<VeltCommentsSidebar groupConfig={groupConfig} />

​
sortData

  • Change the default sorting order of Comments in the Sidebar.
  • Default: desc
There are three options for sorting:
  • asc - to show comments in ascending order of when they were last updated
  • desc - to show comments in descending order of when they were last updated
  • none - to show comments in the sequence they were added
<VeltCommentsSidebar sortData="asc" />

​
setCommentSidebarFilters

  • Programmatically set the system filters on the sidebar:
const filters = {
  location: [
    { id: 'location1Id' },
    { id: 'location2Id' },
  ],
  document: [
    { id: 'document1Id' },
    { id: 'document2Id' },
  ],
  people: [ // author of comment annotation
    { userId: 'userIdToFilter' },
  ],
  involved: [ // user is author or mentioned or assigned
    { userId: 'userIdToFilter' },
  ],
  tagged: [
    { userId: 'userIdToFilter' },
  ],
  assigned: [
    { userId: 'userIdToFilter' },
  ],
  priority: ['P0', 'P1', 'P2'],
  category: ['bug', 'feedback', 'question'],
  status: ['OPEN', 'IN_PROGRESS', 'RESOLVED'],
};

<VeltCommentsSidebar filters={filters} />
API Methods:
const commentElement = client.getCommentElement();
commentElement.setCommentSidebarFilters(filters);

​
systemFiltersOperator

  • Specify whether the system filters (e.g., “me”, “this page”) should be combined with an and or or operator.
  • Default: and
Using Props:
<VeltCommentsSidebar systemFiltersOperator='or' />
Using API:
const commentElement = client.getCommentElement();
commentElement.setSystemFiltersOperator('or');