Workspace / Components

Comparator

Used to compare content side-by-side by highlighting the differences between the original and changed content; can also be used to edit or translate the changed content in place.

Overview

  • Release version
    Zurich
  • Available sinceQuebec
  • A11Y WCAG 2.1 AA
ServiceNow link
Comparator code documentation

UIB and developer guidance

Figma link
Comparator Figma component

Figma library with components for designing Workspace.

Anatomy

Learn about the individual parts of comparator.

Anatomy of the comparator component
  1. Article number: Version number of the article being compared; earlier version article appears on the left and the later version appears on the right
  2. Short description: Short description of the article that is automatically completed when the article number is selected
  3. Previous version: Article body of the earlier version
  4. Deleted content: Indicated with red highlighting and strike-through
  5. Newer version: Article body of the updated version
  6. Added content: Indicated with green highlighting and underlining

Usage

Use comparator to compare different versions of the same document and show the differences. You can configure the editing mode to enable users to make changes to the latest version directly in the component. You can use comparator to compare and edit field values in data records. Users can also select to display a translated version of a document and edit that version.

Example of different versions of a change request record being compared

In this example two versions of a change request record are compared in the Diff mode that highlights the differences.

Variants

Learn about comparator and find out how to use it in your design.

Types

Comparator has 3 configurable types, called modes: Diff, Normal, and Editable.

Diff

The Diff mode is used to compare two versions of same article. It compares the content by highlighting the differences side-by-side. Deleted content is highlighted in red with strike-through. Added content is highlighted in green and underlined. Content can't be edited in this view.

Example of a side-by-side comparison of documents showing highlighted additions and deletions

Normal

The Normal mode is used to display two versions of same article when there is no change in the content between versions. Neither version shows typographical marks, because the content is identical.

Editable

This mode makes the right pane in comparator editable. Any changes made to the content in the version on the right side are saved. This mode can be used to compare and edit an article that has been translated into another language. The user can select the language from the "Translated language" dropdown panel and then edit HTML fields, such as the short description and article body.

Example of a side-by-side translation of an article using the editable comparator type

Configurations

Depending on your use case, you can configure one of 3 comparison modes: Normal, Diff, or Editable. See Types for a description of each mode.

Behavior

Learn how comparator behaves when the display changes or a user interacts with the component.

Interactions

Learn how comparator responds when a user interacts with it.

Opening comparator from a list

A user can select two article versions from the related list of "Article Version" and select the "Compare" UI action in the related list. This action opens a sub tab showing both article versions in a side-by-side comparison in the default, highlighted view.
If the user attempts to compare more than two article versions, a warning appears, advising the user that they can only compare two versions.

Example of the compare action button that opens comparator and the warning that appears when a user attempts to compare more than two versions

Translation

To compare a translated version with the original or to translate the content in the component, the user selects the "Translate" UI action in the details tab. This action launches the editable comparator in a new tab. The user selects the language of the translated content from the dropdown panel. If the content has already been translated, the user can edit string and HTML fields in the content. If the content hasn't been translated, the user can translate it directly in comparator. The instance must have the proper language pack installed to use this feature.

Example of a side-by-side translation of an article using the comparator component.

Usability

Comparator complies with all internationalization and accessibility requirements.

Internationalization

When this component is used in a platform configured for a right-to-left (RTL) language, the article number, short description and the article body align on the right.

Example of a right-to-left language translation in comparator

Accessibility

Learn how to access the actionable elements of comparator through keyboard interactions and screen readers.

Comparator tab order

This is the tab order for comparator.

Example of a side-by-side translation of article using the comparator component

Keyboard interactions

There is read-only keyboard interaction for the Diff and Normal modes. When the Editable mode is used for translation, editable fields in the right pane are accessible with the keyboard.

When the focus is in the "Translated language" dropdown menu:

  • Arrow up, down: Navigates through options in the dropdown menu to select a language
  • Space or Enter: Initiates the option in focus

Screen readers

Screen readers use the built-in table functionality and read the content from left to right following row and column.