​
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

​
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} />

​
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']);

​
floatingMode

  • This makes the sidebar open in an overlay panel over the sidebar button float over the page content.
<VeltSidebarButton floatingMode={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

​
currentLocationSuffix

  • Adds “(this page)” suffix to the group name when the current location matches the group’s location.

Default: false

<VeltCommentsSidebar currentLocationSuffix={true}/>

​
filterPanelLayout

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

​
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} />

​
searchPlaceholder

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

​
System Filters, Sorting and Grouping

​
filterConfig

  • Customize the available system filters:
  • location
  • people
  • priority
  • category
  • status
  • You can rename, disable, configure grouping, and multi-select behavior of the filters as needed.
const filterConfig = {
  location: {
    enable: true,
    name: "Pages", // change the display name of the filter
    enableGrouping: true, // whether to enable grouping based on location filter
    multiSelection: true, // whether to enable multiselection for the filter
    order: ['locationId1', 'locationId2', 'locationId3'] // change the order of the filter options
  },
  people: {
    enable: true,
    name: "People", // change the display name of the filter
    enableGrouping: true, // whether to enable grouping based on people filter
    multiSelection: true, // whether to enable multiselection for the filter
  },
  priority: {
    enable: true,
    name: "Priority", // change the display name of the filter
    enableGrouping: false, // whether to enable grouping based on priority filter
    multiSelection: true, // whether to enable multiselection for the filter
  },
  category: {
    enable: true,
    name: "Category", // change the display name of the filter
    enableGrouping: true, // whether to enable grouping based on category filter
    multiSelection: true, // whether to enable multiselection for the filter
  },
  status: {
    enable: true,
    name: "Status", // change the display name of the filter
    multiSelection: true, // whether to enable multiselection for the filter
  }
}

<VeltCommentsSidebar filterConfig={filterConfig} />

​
groupConfig

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

<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 field is required
		{ id: 'location2Id' }, // id field is required
	],
	people: [
		{ userId: 'userIdToFilter' }, // userId or
		{ email: 'userEmailToFilter' } // user email is required
	],
	priority: ['P0', 'P1', 'P2'], // default supported values
	status: ['OPEN', 'IN_PROGRESS', 'RESOLVED'], // default supported values
	category: ['bug', 'feedback', 'question'], // default supported values
};


<VeltCommentsSidebar filters={filters} />

API Methods:

const commentElement = client.getCommentElement();
commentElement.setCommentSidebarFilters(filters);

Was this page helpful?