Navigation

The navigation object is a collection of functions focused on navigating or redirecting within Relativity, checking recent navigation history, and informing Relativity that a navigation within the current participant has occurred.

1
relativity.navigation

Note: Anything on relativity.navigation not listed in the supported surface area below should not be used, and should be considered volatile (subject to change or removal without warning).

Supported Surface Area of relativity.navigation

navigate

Route to the intended url via nav-prevention for a faster switch, or by redirection if necessary. On the public namespace relativity.

1
navigate(url: string|URL, config: object) : void

• url - the URL or urlString to which the system is being asked to navigate
• config - optional navigation configuration object
• config.omitNavigationConfirmation - if true, navigation confirmation check will be skipped. Defaults to false.

Example:

1
2
3
4
5
const configObject = {
    omitNavigationConfirmation: false
};
relativity.navigation.navigate("https://example.com", configObject);
// window has navigated to https://example.com, no confirmation check was performed

navigateToForms

Navigates to a Relativity Forms layout with the given arguments.

1
navigateToForms(options: object) : void

• options - Options object which contains properties to navigate to specific pages. The properties include:
  • formMode - The form mode for the page ("add", "edit", or "view")
  • artifactTypeId - The ArtifactTypeID for the object type
  • artifactId - The ArtifactID for the object. Required if navigating to a view/edit page
  • parentArtifactId - The ArtifactID for the parent object. Required if navigating to an add page
  • queryStringParameters - Optional key, value pairs of any additional query string parameters

Example:

1
2
3
4
5
6
7
8
9
10
11
12
const options = {
    formMode: "view",
    artifactTypeId: 1000053,
    artifactId: 1040110,
    queryStringParameters: {
        myCustomParameter: "some-custom-value"
        // passing this as a parameter will navigate to a page that
        // contains `?myCustomParameter=some-custom-value` in the URL
    }
};

relativity.navigation.navigateToForms(options);

navigateToListPage

Navigates to a list page with the given arguments.

1
navigateToListPage(options: object) : void

• options - Options object which contains properties to navigate to specific pages. The properties include:
  • artifactTypeId - The ArtifactTypeID for the object type
  • queryStringParameters - Optional key, value pairs of any additional query string parameters

Example:

1
2
3
4
5
const options = {
    artifactTypeId: 10
};

relativity.navigation.navigateToListPage(options);

navigateToReview

Navigates to the review interface for a specific document with the given arguments.

1
navigateToReview(options: object) : void

• options - Options object which contains properties to navigate to specific pages. The properties include:
  • reviewMode - The mode in which the review interface is launched. Can be "edit" or "view"
  • documentId - The ArtifactID for the document
  • queryStringParameters - Optional key, value pairs of any additional query string parameters

Example:

1
2
3
4
5
6
const options = {
    reviewMode: "edit",
    artifactId: 1039789
};

relativity.navigation.navigateToReview(options);

open

Opens a new browser tab/window with the defined url.

1
open(url: string|URL) : void

• url - the destination url for the new tab/window

Example:

1
2
relativity.navigation.open("https://example.com");
// a new browser tab/window has opened to the defined url

peekCurrentUrl

Retrieve the current URL without modifying the stack. If no URL is present (size of history stack is 0), returns empty string.

1
peekCurrentUrl(): string

• Returns string: current URL

Example:

1
2
3
// history: ["someWorkspaceListHref", "someReviewInterfaceHref", "someFormsHref"]
const currentUrlString = relativity.navigation.peekCurrentUrl();
// currentUrlString is now "someFormsHref"

peekPreviousUrl

Retrieve the URL before the current URL without modifying the stack. If no previous URL is present (size of history stack <= 1), returns empty string.

1
peekPreviousUrl(): string

• Returns string: previous URL

Example:

1
2
3
// history: ["someWorkspaceListHref", "someReviewInterfaceHref", "someFormsHref"]
const previousUrlString = relativity.navigation.peekPreviousUrl();
// previousUrlString is now "someReviewInterfaceHref"

popAndNavigateToPreviousUrl

Remove the current URL from the top of the history stack & client-side session storage and route to the previous URL. If no previous URL is present (size of history stack <= 1), the function does no removal and returns false.

1
popAndNavigateToPreviousUrl(): boolean

• Returns boolean: whether this function handled the requested navigation

Example:

1
2
3
// history: ["someWorkspaceListHref", "someReviewInterfaceHref", "someFormsHref"]
relativity.navigation.popAndNavigateToPreviousUrl(); 
// window has navigated to "someReviewInterfaceHref" and history is now: ["someWorkspaceListHref", "someReviewInterfaceHref"]

pushStateAndRecent

Push the href to the in-memory stack & client-side session storage with deduplication if the same href is pushed twice in succession. Additionally adds the URL to the recents and refreshes the favorites in Navigation.Client.

1
pushStateAndRecent(href: string, shouldPushRecent: boolean): Promise

• href - participant href to add to the history stack and recents; supports relative-pathed (path/to/something), absolute-pathed (/path/to/something), and full absolute hrefs (http://example.com)
• shouldPushRecent - Defaults to true. If false, will only push state (change the current url) and will not add to history stack or add to recents.
• Returns promise: resolves when history has been updated

Example:

1
2
3
4
// history: ["someWorkspaceListHref", "someReviewInterfaceHref"]
const hrefToAdd = "someFormsHref";
relativity.navigation.pushStateAndRecent(hrefToAdd);
// history is now: ["someWorkspaceListHref", "someReviewInterfaceHref", "someFormsHref"], "someFormsHref" added to recents

redirect

Explicitly redirect browser (true page navigation) via location assign. On the public namespace relativity.

1
redirect(url: string|URL) : void

• url - the intended destination of the redirection

Example:

1
2
relativity.navigation.redirect("https://example.com");
// window has redirected to https://example.com

redirectHandler

Invokes the redirection handler for Relativity.

1
redirectHandler(mode: string, workspaceId: number, artifactIdentifier: string|number): Promise

• mode - the target mode for redirection handling. The possible modes are:
  • "default-tab" - will redirect to the default tab
  • "dashboard-link" - will redirect to the given dashboard
  • "application-link" - will redirect to the given application
  • workspaceId - workspace ID of the target workspace
  • artifactIdentifier - artifact identifier (ID or GUID)
• Returns promise: resolves upon execution of the redirection

Example:

1
2
relativity.navigation.redirectHandler("dashboard-link", 1234, 5678);
// window has redirected to the given dashboard for the provided workspace

toSearchOrDocument

Performs a redirection to the specified search or document.

1
toSearchOrDocument(workspaceId: number, artifactId: number): Promise

• workspaceId - workspace ID of the target workspace
• artifactId - artifact ID of the target search or document
• Returns promise: resolves upon execution of the redirection

Example:

1
2
relativity.navigation.toSearchOrDocument(1234, 5678);
// window has redirected to the target search or document

toTag

Performs a redirection to the Tag List, pre-selecting the specified field/choice combination.

1
toTag(workspaceId: number, fieldId: number, choiceId: number): Promise<String|undefined>

• workspaceId - workspace ID of the target workspace
• fieldId - artifact ID of the target field
• choiceId - artifact ID of the target choice
• Returns promise: returns the result of the redirection

Example:

1
2
relativity.navigation.toTag(1234, 56, 28);
// window has redirected to the tag list with the specified field/choice combination already pre-selected