You can use the Dashboard SDK's navigate() function to navigate users to pages in the dashboard. These can be pages made by Wix, pages added by your app, or pages added by other 3rd-party apps.
When calling navigate(), you must provide the page ID for the dashboard page to navigate to. For instructions on how to find the page IDs of your app's dashboard pages, and for a full list of Wix page IDs, see Page IDs.
relativeUrl for internal navigationWhen calling navigate(), you can pass a relativeURL. This is a URL segment appended to the base URL of the selected page (destination) that allows you to navigate to a page with some internal state information.
A relativeUrl can include the following:
destination URL passed to navigate(). For example, /some/internal/path.?param1=value1¶m2=value2.#subheading1.To call navigate() with the a relativeURL made from the above examples, you would use the following code:
You can consume an appended URL segment in your code using observeState(). observeState() returns the contextual state of the page in a componentParams object, and environmental information of the dashboard in an environmentState object. The path appended to the page URL by relativeURL is stored in the componentParams object's location.
location contains properties corresponding with those passed in relativeUrl (pathname, search, hash), as well as the pageId.
The example below shows how to access the location object:
dashboard.observeState((componentParams, environmentState) => {
// This value is logged on initialization and whenever either componentParams or environmentState changes.
console.log(componentParams.location);
});
navigate() accepts an optional history parameter with a value of either "push" (default) or "replace". This parameter determines whether the URL of the page being navigated to is added to the browser's session history, or replaces the URL in the current entry.
For example, your dashboard page may contain a table, and you may want any filtering and sorting done on the table to sync with the URL in the address bar so that the user can easily copy and share it. To achieve this you would navigate to the same page with an updated relativeURL. However, every time you navigate this way, the new URL is added to the browser's session history. To prevent this, you can pass {history: "replace"} when calling navigate(). Now instead of adding a new entry, the browser updates the current entry, and the user still only requires 1 "back" or "forward" click to navigate through the page.
navigate() offers 2 options for displaying the page you're navigating to:
Overlay pages allow you to navigate to a related page, like a settings page, without losing the original context. The original page remains in the background, and when the overlay page is closed the user returns to the original page.
Note: The overlay page modal is not related to the dashboard modal extension. Overlay pages are used for navigation, while dashboard modal extensions are intended to get user input in response to an action taken on a dashboard page.
displayModenavigate() accepts an optional displayMode parameter with a value of "main", "overlay", or "auto" (default).
"main" and "overlay" select their corresponding display mode. "auto" (default) causes the page to be loaded in the current context. This means if navigate() is called from the main page, the main page changes. If it's called from an overlay page, the overlay content changes to the new page.
When Wix renders a dashboard page, that page is passed a parameter recording whether it was opened as a main or overlay page. This information allows you to adjust the page's UX or logic accordingly, however in most cases this isn't necessary as Wix handles the adjustments automatically.
You can check this using observeState() to retrieve the componentParams object's displayMode property.
If you call navigate() inside an overlay page using "overlay" or "auto", the new page loads within the same modal.
If you call navigate() inside an overlay page using "main", the overlay page closes and the main page is updated.
If a user navigates back from the first overlay page that was opened in the modal, the modal closes and they return to the original context. If the user then navigates forward, the modal with the overlay page is reopened.
All overlay pages contain an X which closes the modal, and a left arrow with the same behavior as the browser's back button. The navigateBack() function provides a way to implement the back button behavior in code.
The URL in the browser's address bar doesn't change to reflect the URL of the current overlay page. For example, if you navigate from a calendar page to its settings page in the main browser window, the end of the path in the address bar changes from /calendar to /calendar/settings. But if you navigate to the settings page in an overlay page, the path in the address bar remains /calendar.
This has no effect on browser navigation, only what appears in the browser's address bar, so users can navigate back and forward between pages as normal within and outside the overlay page modal. (The URLs of pages opened in overlay mode are added to the browser's session history as normal.)