Use this guide to learn about migrating common integrations from the legacy HTML5 document viewer to the new Relativity Review Interface.
This page contains the following information:
In the Relativity Review Interface, you implement a custom pane by defining a custom card for it rather than by defining it in a database.
See the following sections about migrating custom panes:
In the legacy review interface, a custom pane was defined by running SQL statements on a database:
DECLARE @ImageData AS VarBinary(max)
SET @ImageData = (SELECT * FROM OPENROWSET(BULK N'C:\Relativity.png', SINGLE_BLOB) X)
INSERT INTO [Pane]([HeaderText], [Type], [Src], [ImageFilename], [Order], [Data], [ImageFileData], [AutoRefresh])
VALUES ('Header', 'type', 'https://www.relativity.com/relativity/resources/release-archives/9-0/', 'footer-logo-2x.png', 2, '', @ImageData, 1)In the Relativity Review Interface, implement the custom pane as card config object:
var testCardConfig = {
id: "type",
title: "Header",
icon: {
url: "https://www.relativity.com/relativity/images/footer-logo-2x.png",
},
singleton: true,
location: {
layoutId: "review",
paneId: "ri-review-right-accordion",
dockIndex: 0,
},
loader: {
iframe: {
url: "https://www.relativity.com/relativity/resources/release-archives/9-0/",
},
},
};To migrate a custom pane, you need to map the values from the columns in the Pane table to properties on a config object for a custom card.
The following list explains how to map the value in a table column to a property on the config object:
Note: Set the location to where the custom card displays in the card system. This property wasn't previously defined in the Pane table.
See these pages for more information about custom panes:
The Relativity Review Interface introduces a new viewer architecture, built on the Card framework. It offers the following advantages over the legacy HTML5 document viewer:
More control over document types that use a custom viewer
In the legacy HTML5 document viewer, you could only use the file type of a document native to determine whether the custom viewer should be loaded. Now, you have the option to use any criteria, including file type. See Creating Viewer Types.
Better performance
Navigating through documents that use custom and core viewer types is faster because full page loads aren't required for custom viewer types. The faster navigation provides a better user experience.
More control over how custom viewers display
In the Relativity Review Interface, you can control where the viewer type is displayed. You can place custom viewers alongside core viewer types, or they can replace core viewer types, like the image, text, or production viewers. The legacy document viewer only permitted custom viewers to replace the native viewer. See Viewer Tabs and Custom Viewer Types.
In contrast, the legacy HTML5 document viewer supports custom viewers based on entries in the [EDDSDBO].[DocumentViewerMapping] table in a workspace database. The table entries map document file types in the [DocumentFileType] column to the URL of a custom page in the [ViewerURL] column, which should load to view a document. When a user navigates to a document with this file type in the native viewer, the URL is loaded instead of the native viewer.
Note: The legacy review interface continues to load the entries in [DocumentViewerMapping] table, but the Relativity Review Interface ignores them.
To migrate a context menu, you need to map legacy values from a database table and replace tokens used in certain JavaScript functions. The following sections provide examples of legacy and migrated context menus, and instructions for completing the migration steps:
In the legacy HTML5 document viewer, you were required to add viewer context menu items to the ViewerContextMenuItem table in the workspace database.
The following SQL statement creates legacy context menu items, including a parent item and a child item that fires a browser alert when clicked:
INSERT INTO [ViewerContextMenuItem]([Name], [Action], [Availability], [Order], [RequiresSelectedText], [JavascriptEncodeSelectedText], [XMLEncodeSelectedText], [ParentMenuItemID], [AssociatedSearchProviderID], [AssociatedPermissionID])
VALUES('Parent', '', 0, -1, 0, 0, 0, NULL, NULL, NULL)
DECLARE @ParentMenuID INT = @@IDENTITY
INSERT INTO [ViewerContextMenuItem]([Name], [Action], [Availability], [Order], [RequiresSelectedText], [JavascriptEncodeSelectedText], [XMLEncodeSelectedText], [ParentMenuItemID], [AssociatedSearchProviderID], [AssociatedPermissionID])
VALUES ('Child', 'alert(''Menu Item!'')', 0, -1, 0, 0, 0, @ParentMenuID, NULL, NULL)In the Relativity Review Interface, set the IExtensionConfig.viewerContextMenus of the extension script to the following function, which creates the equivalent context menu items:
function(api, viewerType) {
return [{
text: "Parent",
childItems: [{
text: "Child",
order: -1,
onClickCallback: function(reviewData, api) {
alert("Menu Item!");
},
}],
order: -1,
}];
}To migrate a context menu, you need to map the values from the columns in the ViewerContextMenuItem table to properties on an IContextMenuItemConfig object in the Relativity Review Interface.
The following list explains how to map the value in a table column to a property:
Availability column - implement an IExtensionConfig.viewerContextMenus function based on the behavior in the Availability column.
Note: The IExtensionConfig.viewerContextMenus and IContextMenuItemConfig.onBuildCallback support enabling or disabling the context menu item based on criteria other than viewer type.
Use the following settings:
1 or 2 - Use the viewerType to determine the availability of the context menu item. The array returned by IExtensionConfig.viewerContextMenus conditionally includes this item. In the following example, the Availability value of 1 indicates native and text modes:
function(api, viewerType) {
if (viewerType === "native" || viewerType === "text") {
return [{
text: "My Context Menu Item",
order: 10,
onClickCallback: function(reviewData, api) {
alert("Hello world");
}
}];
}
return [];
}For the Availability value of 2, update the conditional statement to image and production viewers as follows:
if (viewerType === "image" || viewerType === "production") { ... }Order column - set the IContextMenuItemConfig.order property to the value in this column.
The legacy review interface supports several tokens in JavaScript for the context menu item. In contrast, the Relativity Review Interface requires you to pass an {@link IContextMenuReviewData} object to the IContextMenuItemConfig.onClickCallback function.
See these pages for more information about context menu integrations:
The following code sample illustrates how to replace JavaScript tokens for context menu items in the legacy review interface by using the {@link IContextMenuReviewData} object:
var onClickCallback = function (reviewData, api) {
// AppID
var appId = reviewData.workspaceId;
// DocumentArtifactID
if (
reviewData &&
reviewData.queuePointer &&
reviewData.queuePointer.item &&
reviewData.queuePointer.item.type === "document"
) {
// when item.type is RDO, for example, item.artifactId won't be defined
var documentArtifactId = reviewData.queuePointer.item.artifactId;
}
// SelectedText
var selectedText = reviewData.getSelectedText();
// CursorX and CursorY
var cursorX = reviewData.cursor.x;
var cursorY = reviewData.cursor.y;
};For document layouts, the use of event handlers has changed as follows:
Legacy review interface - In this interface, Page Interaction event handlers are used to customize the look and feel of the coding layout. For more information, see Page Interaction event handlers on the RelativityOne Developers site.
New Relativity Review Interface - In this interface, Relativity Forms event handlers replace the legacy Page Interaction event handlers. For more information, see Relativity Forms API on the RelativityOne Developers site.
To migrate a Page Interaction event handler, convert it to a Relativity Forms event handler. For detailed instructions, see Converting the page interaction event handler in Sample: Converting a Classic Form to a Relativity Form on the RelativityOne Developers site.