About Dashboard Page Navigation

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.

Using relativeUrl for internal navigation

When 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:

  • Pathname: Parts of a URL path to append to the base destination URL passed to navigate(). For example, /some/internal/path.
  • Search: A string containing search (query) params used to set the internal state of the page. For example, ?param1=value1&param2=value2.
  • Hash (fragment identifier). Typically used to identify some content on the page. For example, #subheading1.

To call navigate() with the a relativeURL made from the above examples, you would use the following code:

Copy

Consuming URL segments

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); });

Managing navigation history

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.

See also

Did this help?